eMerge

Development Guide

Server Software: V4.5R2.0 Client Software: V4.5R2.0 Edition: 18 April 2010

eMerge Development Guide 18 April 2010 Copyright 19822010 Sapiens International Corporation N.V. All rights reserved.

Information in this document is provided for informational purposes only, is subject to change without notice, and does not represent a commitment on the part of Sapiens Technologies (1982) Ltd. ("Sapiens Technologies") or Sapiens International Corporation N.V. ("Sapiens International"). This manual, and the software described in it, are furnished under a license agreement or nondisclosure agreement. The software may only be used or copied in accordance with the terms of such agreement. Except as may be otherwise permitted by such agreement, no part of this manual may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, for any purpose without the express written permission of Sapiens Technologies. Neither Sapiens International nor Sapiens Technologies assumes any responsibility or liability for any errors or inaccuracies that may appear in this manual. Sapiens Technologies is an indirect wholly owned subsidiary of Sapiens International. SAPIENS is a registered trademark and Sapiens eMerge (including Development Workbench, Modeler, i.way, Business Integrity Server, RuleScribe, and Legacy Adapter), FALCON, and Sapiens Euro Migration are trademarks of Sapiens International. Other brands and product names are trademarks of their respective holders. Brand and product names are mentioned herein for reference purposes only.
EMERGE-DEVGUIDE-V4.5R2.0

We welcome your questions and comments about the documentation. Send e-mail to: [email protected].

Table of Contents

eMerge Documentation

xix

Part A
Chapter 1

Introduction
About This Guide 3 eMerge Application Development 1.1 Building an eMerge Application 1-1 1.2 Data Structure in eMerge 1-3 1.3 Modeling Your Application 1-7 1.4 Application Development Stages 1-10 1.5 Data Access and Manipulation 1-13 1.6 Presentation 1-15

Part B
Chapter 2

Data
Analysis StageBuilding a Concept Model 2.1 Concept Model 2-1 2.2 Inserting a New Concept Model 2-2 2.3 Reviewing and Modifying an Existing Model 2-4 2.4 Type of Concept 2-5 2.5 Inserting a Concept 2-7 2.6 Defining a Dependency Association between Entities 2.7 Extending the Concept Definition 2-19 Analysis StageDefining Fields and Domains 3.1 Types of Concept Fields 3-1 3.2 Data Type for a Field 3-2 3.3 Defining Fields for a Concept 3-5 3.4 Domain Concept 3-7 3.5 Defining a Domain 3-8 3.6 Advancing a Concept to Design or Implementation 3.7 Retreating to Analysis 3-14 Design Stage of a Concept 4.1 Design Stage 4-1 4.2 Main Designs and Opposite-To-Main Designs 4-1 4.3 Default Designs and User Designs 4-3 4.4 Physical Designs and Operation Designs 4-3
iii

2-16

Chapter 3

3-12

Chapter 4

4.5 4.6 4.7 4.8 4.9 4.10 4.11 4.12 4.13 4.14 4.15 4.16 4.17 4.18 Chapter 5

Options 4-4 Which Fields are Used 4-7 Link Between the Concept and its Parent 4-7 Changing the Parent Design Used by a Dependent Concept Structure 4-9 Modifying the Main Design 4-11 Creating a New Design 4-12 Modifying an Existing Design 4-13 Design Examples 4-14 Illustrations of Default Designs 4-16 Automatic Fields and Shared Parents 4-24 Advancing a Concept to Implementation 4-27 Retreating to Design 4-28 Retreating to Analysis 4-29

4-9

Implementation Stage of a Concept 5.1 Implementation Stage 5-1 5.2 Testing the Application 5-2 5.3 Working with Implemented Concepts 5-2 5.4 Defining Default Values for a Field 5-3 5.5 Defining a Global Default Value 5-4 5.6 Using Synonyms 5-5 5.7 Listing Composite Structures 5-9 5.8 Automatic Rules 5-11 5.9 Retreating to Design or Analysis 5-12 Working with the Concept Model 6.1 Excluding a Concept 6-1 6.2 Deleting a Concept 6-1 6.3 Deleting a Dependency Association 6-1 6.4 Deleting a Model 6-2 6.5 Opening a Concept from the Navigation Pane 6-2 6.6 Moving a Concept 6-3 6.7 Resizing a Concept 6-3 6.8 Changing the Parent of a Concept 6-4 6.9 Changing the Type of a Concept 6-4 6.10 Changing the Connector Ports of a Concept 6-5 6.11 Exporting a Concept Model to an External UML Tool Viewing Models 7.1 Switching between Local and Global View 7.2 Changing the Local View 7-2 7.3 Finding a Particular Model Object 7-4 Printing and Generating Reports 8.1 Printing a View of a Model 8.2 Modeler Reports 8-3 Object Number Selection 8-1 7-1

Chapter 6

6-6

Chapter 7

Chapter 8

Chapter 9

iv

9.1 9.2 9.3 9.4 9.5 9.6

Rangeset and Complexity for a Model Rangeset and Complexity for an Entity Complexity for a User Design 9-8 Rangeset for a Domain 9-9 Rangeset for a Ruleset 9-11 Working with Privacy 9-13

9-4 9-6

Part C

Logic
What is Logic 10.1 Built-in Application Logic 10-1 10.2 User-defined Application Logic 10-2 10.3 Rule Model 10-3 Analysis Stage: Building a Rule Model 11.1 Rulesets 11-1 11.2 Triggering Object 11-1 11.3 Ruleset Triggering Order Within a Model 11-3 11.4 Triggering Order for Rulesets Attached to Different Objects 11.5 Creating a Ruleset with a Triggering Object 11-5 11.6 Creating a Ruleset without a Triggering Object 11-10 11.7 Attaching a Ruleset to a Triggering Object 11-13 11.8 Viewing or Modifying a Ruleset Rule Model 11-14 11.9 Documenting a Ruleset 11-14 11.10 Displaying Ruleset Information 11-15 11.11 Defining Rules for a Ruleset 11-16 11.12 Types of Rules 11-17 11.13 The Rule Context 11-19 11.14 Fields in Rules 11-21 11.15 Positioning a Rule 11-22 11.16 Executing Rules in a Ruleset 11-22 11.17 Inserting a Rule in a Rule Model 11-24 11.18 Computation Rule 11-25 11.19 Validation Rule 11-25 11.20 Fetch Rule 11-26 11.21 FetchSQL Rule 11-29 11.22 Derivation Rule 11-30 11.23 Call Rule 11-33 11.24 Component Rule 11-36 11.25 Post Rule 11-37 11.26 Nontyped Rule 11-38 11.27 Copying a Rule 11-39 11.28 Documenting a Rule 11-40 Design Stage: Composing Rules 12.1 Advancing a Rule to Design 12-1 12.2 Using Synonyms to Reference Knowledgebase Objects 12.3 Making a Rule Conditional 12-4

Chapter 10

Chapter 11

11-5

Chapter 12

12-4

12.4 12.5 12.6 Chapter 13

Fields in Rules 12-6 Temporary Fields 12-6 Dynamic Fields 12-10

Rule Editor 13.1 Rule Text Categories 13-2 13.2 Prompting for Keywords and Data Objects 13-3 13.3 Prompter Options 13-4 13.4 Prompting for Functions 13-8 13.5 Checking Rule Syntax 13-10 13.6 Editing Rule Text 13-10 13.7 Changing Formatting for Display of Rule Text 13-11 Implementation Stage of a Rule 14.1 Requirements for Implementing a Rule 14.2 Implementing a Rule 14-2 14-1

Chapter 14

Chapter 15

Working with the Rule Model 15.1 Viewing Details of Objects 15-1 15.2 Changing the Execution Order of Rulesets and Rules 15-2 15.3 Copying a Ruleset or a Rule 15-3 15.4 Deactivating a Ruleset or Rule 15-6 15.5 Deleting a Ruleset or Rule 15-7 15.6 Listing Ruleset Triggering Objects 15-8 15.7 Detaching a Ruleset or Target Object 15-8 15.8 Fully Detaching a Ruleset or Target Object 15-9 15.9 Reattaching a Ruleset to a Different Object 15-9 15.10 Excluding a Ruleset or Target Object 15-10 15.11 Replacing a Ruleset 15-10 15.12 Rule Reengineering 15-11 15.13 Exporting Rules within Concept Models to External UML Tools

15-12

Chapter 16

Using a Computation Rule 16.1 Specifying a Computation Rule 16-2 16.2 Computation Rule Syntax 16-3 16.3 Computing a Value to be Stored and/or Displayed 16-4 16.4 Using Temporary Fields 16-10 16.5 Initializing Values 16-10 16.6 Calculations Involving Date Fields and Hexadecimal Fields 16-11 16.7 Calculating a Value Conditionally 16-12 16.8 Calculating a Value Dependent on the Operation Code 16-13 16.9 Calculating a Value Based on an Iterative Process 16-13 Using a Validation Rule 17.1 Specifying a Validation Rule 17-2 17.2 Validation Rule Syntax 17-3 17.3 Validating Against a Constant or Set of Constants 17.4 Validating Against a Calculated Value 17-6 17.5 Checking Against Another Field 17-6

Chapter 17

17-4

vi

17.6 17.7 17.8 17.9 17.10 17.11 17.12 Chapter 18

Checking Validity Against a Mask 17-6 Checking Validity When Using Special Characters 17-8 Validating a Field Conditionally 17-8 Validating a Field Dependent on the Operation Code 17-9 Validating Fields in Other Concept Designs 17-10 Continuing Processing After a Validation Fails 17-11 Ensuring that a Validation Fails 17-11

Using a Fetch Rule 18.1 Specifying a Fetch Rule 18-1 18.2 Fetch Rule Syntax 18-9 18.3 Retrieving a Value From a Target Occurrence 18-11 18.4 Storing a Retrieved Value 18-11 18.5 Retrieving the Closest Existing Value 18-12 18.6 Retrieving a Dependent Target Occurrence 18-13 18.7 Retrieving an Occurrence from the Same Object Hierarchy 18-13 18.8 Retrieving a Group of Target Occurrences 18-15 18.9 Checking Fields in Other Target Objects 18-16 18.10 Fetching a Value Conditionally 18-18 18.11 Initializing Values Using a Fetch Rule 18-19 18.12 Calculating a Value Dependent on the Operation Code 18-20 18.13 Continuing Processing After a Fetch Fails 18-20 18.14 Field Values in Rule Context 18-21 18.15 Target Specification via Fetch Rule Syntax 18-22 18.16 Specifying a Find Action for a Fetch Rule 18-24 18.17 Fetching Information via All Paths to Target Class 18-26 Using a FetchSQL Rule 19.1 Specifying a FetchSQL Rule 19-1 19.2 FetchSQL Rule Syntax 19-8 19.3 Retrieving SQL Data 19-11 19.4 Continuing Processing After a FetchSQL Fails 19-14 19.5 Listing Rules Using the Same SQL View 19-14 19.6 Replacing Strings in an SQL View Statement 19-15 19.7 Handling SQL Multi-Platform Syntax Issues 19-18 Using a Call Rule 20.1 Specifying a Call Rule 20-1 20.2 Call Rule Syntax 20-3 20.3 Other Methods to Create a Call Rule 20-5 20.4 Calling a Ruleset Conditionally 20-6 20.5 Calculating a Value Dependent on the Operation Code 20.6 Calling a Program 20-7 Using a Derivation Rule 21.1 Specifying a Derivation Rule 21-2 21.2 Derivation Rule Syntax 21-6 21.3 Writing to a Target Object Occurrence 21-7 21.4 Writing to a Parent Target Object Occurrence

Chapter 19

Chapter 20

20-7

Chapter 21

21-7
vii

21.5 21.6 21.7 21.8 21.9 21.10 21.11 21.12 21.13 21.14 21.15 Chapter 22

Writing a New Target Object Occurrence 21-10 Writing to an Existing Target Occurrence 21-14 Generating a Parent Occurrence Automatically 21-15 Ignoring a Missing Target Occurrence 21-17 Copying an Occurrence 21-18 Field Values in Rule Context 21-19 Target Specification via Derivation Rule Syntax 21-19 Specifying an Operation as the Target for a Derivation Rule Derivation Rule Syntax with Target Specification 21-22 Invoking an Operation via a Derivation Rule 21-24 Derivation Rule Syntax for Invoking an Operation 21-26

21-20

Dynamic Rule Processing 22.1 Dynamic Fields in Rules 22-1 22.2 Target Specification via Derivation Rule Syntax 22-2 22.3 Derive via Operations 22-3 22.4 Derivation Rule Syntax with Target Specification 22-5 22.5 Invoking an Operation via a Derivation Rule 22-8 22.6 Derivation Rule Syntax for Invoking an Operation 22-9 22.7 Target Specification via Fetch Rule Syntax 22-12 22.8 Fetch Rule Syntax with Target Specification 22-13 Temporary Composites 23.1 Options Supported 23-2 23.2 Enabling Temporary Composites 23-2 23.3 Defining a Temporary Composite 23-3 23.4 Using Temporary Composites with Derivation Rules Using Built-In Functions in Rules 24.1 What are Functions? 24-1 24.2 Built-In Functions 24-2 24.3 Function Syntax 24-5 24.4 Function Categories 24-6 24.5 Accessing a Function Category 24-6 24.6 Accessing a Function Definition 24-7 24.7 Implementing Functions in a Rule 24-8 24.8 Examples of Functions in Rules 24-9 Using User-Defined Functions in Rules (i5/OS, HP-UX, and Linux) 25.1 What are Functions? 25-1 25.2 Function Syntax 25-2 25.3 Function Categories 25-2 25.4 Function Definitions 25-3 25.5 Module Generation and Compilation 25-8 25.6 Specifying the User-defined Function 25-8 25.7 Implementing Functions in a Business Rule 25-9 25.8 Example of Functions in a Computation Rule 25-10 Improving Rule Performance

Chapter 23

23-5

Chapter 24

Chapter 25

Chapter 26

viii

26.1 26.2 Chapter 27

Accessing a Target Object in Memory 26-1 Changing the Execution Order for Target Objects

26-2 27-1

Looping and Recursion 27.1 Allowing Recursion Caused by a Derivation Rule 27.2 Preventing Single-Level Data Looping 27-2 27.3 Preventing Multiple-Level Data Looping 27-4

Chapter 28

Additional Rule Features 28.1 Dynamically Calling a Ruleset 28-1 28.2 Using Dynamic Calls 28-3 28.3 Old and New Values Affecting Dynamic Calls 28-5 28.4 Limiting the Objects Causing Rule Execution 28-5 28.5 Controlling the Values Used by a Rule 28-7 28.6 Triggering Dependent Rules Automatically 28-8 28.7 Specifying a Site-Ruleset Based on Metadata Definitions Debugging Rules 29.1 Reporting About Rulesets and Rules 29-1 29.2 Tracing Ruleset and Rule Execution 29-5 29.3 Trace Output 29-5 29.4 Setting Rule Traces 29-7 29.5 Viewing Rules with Trace Option On 29-10 29.6 Tracing Fetch Rules and Derivation Rules 29-11 29.7 Using a Trace Path 29-16 29.8 Deactivating Rulesets and Rules 29-17

28-9

Chapter 29

Chapter 30

Handling Errors 30.1 Displaying an Existing eMerge Message 30-1 30.2 The ERROR DETAILS Command 30-2 30.3 Displaying a Different Message 30-2 30.4 Overriding an Error Message 30-7 30.5 Invoking a Ruleset Whenever an Error is Issued 30-11 30.6 Replacing a Message Based on an Internal Field Value 30-11 30.7 Branching to Another Form 30-16 30.8 Branching to Another Form for a Form, Operation or Rule 30-17 30.9 Branching to Another Form for a Field Value 30-18 Rule Analyzer 31.1 Impact Analysis 31-2 31.2 Conflict Analysis 31-3 31.3 Sequencing Analysis 31-4 31.4 Rule Analyzer via Development Workbench 31.5 Performing an Impact Analysis 31-8 31.6 Performing a Conflict Analysis 31-18 31.7 Performing a Sequencing Analysis 31-22 31.8 Rule Analyzer in Batch 31-26 31.9 SAPANLYS Program 31-26

Chapter 31

31-4

ix

Part D

Accessing the Data

Accessing the Data Operations and Operation Methods 33.1 Invoking Operations 33-2 33.2 Operation Design 33-2 33.3 Defining a New Operation 33-4 33.4 Specifying an Operation Design Without a Target 33.5 Customizing an Operation 33-9 33.6 Modifying an Existing Operation Design 33-12 33.7 Operation Design Example 33-14 33.8 Defining a Banner Operation 33-15 33.9 Processing Operations in Groups 33-19 33.10 Deleting an Operation 33-20 33.11 Using Synonyms 33-21 33.12 Rulesets Triggered by Operations 33-21 33.13 Operation Methods 33-22 33.14 Built-in Operation Methods 33-25 33.15 User-defined Operation Methods 33-26 33.16 Defining an Operation Method 33-28

Chapter 32 Chapter 33

33-8

Part E

Presentation
What is the Presentation 34.1 Planning the Presentation 34-1 34.2 Building an Application 34-2 34.3 Types of Forms 34-3 34.4 Using Form Editor 34-9 34.5 Accessing Form Definition for a Form 34-11 34.6 Selecting Form Objects for Editing 34-12 34.7 Moving Objects Around the Form 34-13 34.8 Adding and Modifying Text on a Form 34-14 34.9 Adding Lines 34-17 34.10 Adding Rectangles 34-17 34.11 Adding Groupboxes 34-18 34.12 Customizing Colors 34-19 34.13 Changing the Colors of Form Objects 34-20 34.14 Defining Colors for the Field in Focus and Actions 34-23 34.15 Adding Images to a Form 34-23 34.16 Aligning Form Objects 34-26 34.17 Adjusting Spacing Between Form Objects 34-28 34.18 Resizing Objects 34-29 34.19 Assigning or Removing an Option for Multiple Fields 34-31 34.20 Undoing Modifications 34-32 34.21 Adding Meta Tags to eMerge Forms 34-33 Data Forms

Chapter 34

Chapter 35

35.1 35.2 35.3 35.4 35.5 35.6 35.7 35.8 35.9 35.10 35.11 35.12 35.13 35.14 35.15 35.16 Chapter 36

Creating a Data Form 35-1 Defining a Data Form 35-2 Defining a Block 35-4 Modifying a Block 35-7 Working with a TableControl Block 35-17 Defining a Tab Control 35-21 Inserting an Action into a Data Form 35-30 Entry and Exit Commands for a Data Form 35-32 Field Display Types 35-33 Customizing Field Presentation 35-40 Changing Tab Order 35-48 Displaying Binary Large Objects 35-50 Multilingual Forms 35-54 Evaluating Initial Form Display 35-54 Example of a Customized Single Occurrence Data Form 35-55 Example of a Customized Multioccurrence Form 35-56

Menu Forms 36.1 Defining a Menu 36-1 36.2 Customizing Menu Forms 36-3 36.3 Including Data in a Menu via Menu Fields 36-4 36.4 Defining a Menu with Only One Option 36-6 36.5 Defining a Popup Menu for a Field in a Data Form Tree Compound Forms 37.1 Creating a Tree Compound Form 37-2 37.2 Modifying a Tree Compound Form 37-3 37.3 Tree Forms 37-3 37.4 Modifying a Tree Form 37-10 37.5 Customizing a Popup Menu 37-16 37.6 Automatic Refresh of the Tree Control 37-17 Select and Detail Forms 38.1 Select Forms 38-2 38.2 Detail Form 38-3 38.3 Enabling Select or Detail Forms 38.4 Search Order 38-7

36-6

Chapter 37

Chapter 38

38-4

Chapter 39

Form Actions 39.1 Adding a Form Action to a Form 39-2 39.2 Tooltips for Form Actions 39-5 39.3 Access Key for Action Buttons 39-6 39.4 Action Inheritance 39-8 39.5 Defining the Enter Key as an Action 39-11 Presentation Components for Forms 40.1 Interoperate with Other Applications 40.2 Enhance Appearance and Functionality 40.3 How to Utilize a Component 40-7 40-2 40-2

Chapter 40

xi

40.4 40.5 40.6 40.7 40.8 Chapter 41

Supported Categories 40-11 Utilizing a URL Component 40-12 Utilizing a SCRIPT Component 40-19 Utilizing a Java Applet Component 40-26 Utilizing an ActiveX Component 40-35

Displaying Values on Accessing a Form 41.1 Displaying Data on Accessing a Data Form 41-1 41.2 Defining a Default Value for a Field in a Form 41-7 41.3 Passing Data to and From Menus 41-10 Security for Forms 42.1 Defining a Forms Privacy Level 42-2 42.2 Examples of Privacy Levels 42-2 42.3 Overriding Default Privacy 42-4 Form Templates 43.1 What is a Template? 43-1 43.2 Embedded Templates 43-3 43.3 Dynamic Templates 43-4 43.4 Defining an Embedded Form Template 43-5 43.5 Defining a Dynamic Form Template 43-8 43.6 Applying Templates 43-10 Form Components 44.1 What is a Form Component 44-1 44.2 Flows Across Modules 44-1 44.3 Linking a Form from One Module to a Form in Another Module 44.4 Defining Domains 44-10 44.5 Defining a Top Form for a User 44-13

Chapter 42

Chapter 43

Chapter 44

44-4

Part F

Help for Applications

Documentation and Help Text for Applications 45.1 Documenting Knowledgebase Objects 45.2 End User Help Text for Fields 45-2 45-1

Chapter 45

Part G

Reports and Queries

Reporting 46.1 Listings 46-1 46.2 Information Tools 46-1 46.3 Querying and Manipulating Data 46-2 46.4 Querying Temporary Composites 46-2 46.5 Complex Reporting and Data Manipulation Basic Reports via Retrieval Operation Codes 47.1 Operation Codes 47-1 47.2 Showing the Listing as a Report 47-2 47.3 Changing a Field Name Displayed in a Listing

Chapter 46

46-2

Chapter 47

47-3

xii

47.4 Chapter 48

Listing Additional Information

47-4

Information Tools 48.1 How To Search 48-2 48.2 Searching for Rulesets 48-3 48.3 Searching for Rules 48-4 48.4 Searching for Queries 48-7 48.5 Searching for Error Text 48-8 48.6 Searching for BLP Commands 48-9 48.7 Using the Search Tools in Batch 48-10 Cleanup Tools 49.1 Cleaning up the Database 49.2 Cleaning up Constructors 49-2 49-3

Chapter 49

Chapter 50

Introduction to Queries 50.1 Defining a Query 50-1 50.2 Queries in a Multi-Language Environment 50-4 50.3 The Query Instruction Statement 50-4 50.4 Using Queries with a Century Window 50-6 50.5 Compiling and Running a Query 50-6 50.6 Viewing the Query Output 50-8 50.7 Viewing Sample Output via the DEMOQUERY Command Basic Queries 51.1 Selecting and Qualifying Data for a Query 51-1 51.2 Defining Output Type and Style for a Query 51-4 51.3 Arranging the Data Printed in a Report 51-4 51.4 Breaking Up the Output 51-10 51.5 Improving a Report's Appearance 51-16 51.6 Defining Comment Text for a Query 51-20 51.7 Renaming a Field for a Query 51-21 51.8 Using Possible Values in the Query Output 51-23 51.9 Using Statistical Functions 51-23 51.10 A Summary of Basic Query Statements 51-28 Extending the Use of Queries 52.1 Parametric Queries 52-1 52.2 Including a Query in Another Query 52-2 52.3 Improving Performance When Using Object Ranges in Queries 52.4 Querying Knowledgebase Objects 52-6 52.5 Using Virtual Fields 52-6 52.6 Using Virtual Classes (Views) 52-11 Sending Query Output to a Data Entry Form 53.1 Writing a Query Using a FORM 53-1 53.2 Customizing the Output Form 53-3 53.3 Using the Query Output Form as Part of a Flow 53-3 53.4 Using the EDIT Statement to Manipulate the Output 53-4 53.5 Including More than One Block in an Output Form 53-8

50-8

Chapter 51

Chapter 52

52-3

Chapter 53

xiii

Chapter 54 Chapter 55

Extracting Raw Data to an External File Updating the Database Using Queries 55.1 Updating Dates 55-2 55.2 Updating the Database Immediately 55-2 55.3 Changing Existing Data 55-2 55.4 Deleting Data 55-4 55.5 Inserting Data 55-5 55.6 Maintaining Database Integrity With an UPDATE Statement Using SQL in a Query 56.1 Defining an SQL Query 56-1 56.2 The DEFINE SQL Statement 56-4 56.3 Defining More than One SQL Query in a Query 56.4 SQL Parametric Queries 56-7 56.5 Sample Queries 56-9 56.6 Mode of ExecutionDynamic vs. Static 56-14 56.7 SQL I/O Module 56-15 56.8 Linking a Query to an I/O module 56-17

55-7

Chapter 56

56-7

Chapter 57

Advanced SQL Queries 57.1 SQL Query Processing in the eMerge Method 57-1 57.2 Coupling Selected Columns in the eMerge Method 57-2 57.3 Implicit Matching 57-2 57.4 Explicit Matching 57-3 57.5 Qualified Field Names 57-4 57.6 Matching Columns via a Table Designator 57-5 57.7 Duplicate Columns from Different Queries 57-7 57.8 Matching Unspecified SQL Names 57-7 57.9 Matching Algorithm Summary 57-7 57.10 Referencing SQL Columns in the eMerge Method 57-8 57.11 Referencing Compound Names in the eMerge Method 57-11 57.12 Working with Zoned Data Type in i5/OS 57-11 57.13 Replacing Strings in an SQL View Statement 57-12 57.14 Handling SQL Multi-Platform Syntax Issues 57-15 Common Query Errors 58.1 Syntax Errors 58-1 58.2 Logic Errors 58-3 58.3 Format Errors 58-5 58.4 Error Messages When Running in Batch

Chapter 58

58-7

Part H

External Programs
Calling External Programs from eMerge 59.1 Using External Programs 59-1 59.2 Calling from Messages or Rules 59-1 59.3 Supported Programming Languages 59-1 Calling C Programs from eMerge Under i5/OS, HP-UX and Linux

Chapter 59

Chapter 60
xiv

60.1 60.2 60.3 60.4 60.5 60.6 60.7 60.8 60.9 60.10 60.11 Chapter 61

Creating a Program to be Run from eMerge 60-1 Create the C Program 60-2 Compile and Link the C Program 60-3 Define the Program in the eMerge Program Definition Form Define the Fields, Operation and Forms 60-6 Define a Ruleset to Invoke the C Program 60-10 Define a Ruleset to Pass Program Parameters 60-10 eMerge.h Header File 60-12 Templates for Private Header Files 60-12 Data Types 60-13 Example Files 60-14

60-5

Using SAPUTMON to Access Business Integrity Server via External Programs 61.1 Stages of a Business Integrity Server Session 61-1 61.2 Parameters for Business Integrity Server Initialization 61-2 61.3 Parameters for Session Logon 61-5 61.4 Parameters for a Session 61-6 61.5 Linking to SAPUTMON 61-7 61.6 Sample Programs 61-9

Part I

Multilingual Applications
Applications with More than One Language 62.1 Introduction 62-1 62.2 Defining Applications for Use in More than One Language 62-2 62.3 Defining Concepts in More than One Language 62-3 62.4 Defining Constructors in More than One Language 62-4 62.5 Multilocale ApplicationsUsing More than One Code Page 62-6 62.6 Defining a Field to Accept Data in More than One Language 62-13 62.7 Defining a Field to Display Data in the Current Language 62-15 62.8 Defining a Field to Display Data in the Locale Language 62-17 62.9 Defining Possible Values 62-18 62.10 Language-Dependent Forms 62-18 62.11 Using DBCS Languages 62-19 62.12 Using a Right-to-Left Language 62-22 62.13 Restrictions for Working with More than One Language 62-23

Chapter 62

Part J

Change Management
Working with Change Management 63.1 Change Management Tasks 63-1 63.2 Migration Units 63-2 63.3 Checks Performed During Application Development 63.4 Choosing a Task 63-3

Chapter 63

63-2

Part K

Development Privacy
Working Under Development Privacy
xv

Chapter 64

64.1 64.2 64.3 64.4 64.5

Concept Model 64-1 Rule Model 64-3 Rule Editor Privacy Checks 64-4 Inheritance of Privacy 64-6 Writing Queries for Runtime Privacy Definitions

64-7

Part L

eMerge Applications via 3270-Display

eMerge Applications via 3270-Display 65.1 Accessing eMerge Forms via 3270-Display 65-1 65.2 Navigating a Form 65-2 65.3 eMerge 3270-Display Forms 65-2 65.4 System Actions 65-4 65.5 Data Form Format 65-5 65.6 Menu Format 65-7 65.7 Select and Detail Forms 65-7 65.8 Erasing Individual Values in the Database 65-10 65.9 Issuing Commands 65-11 65.10 Viewing and Printing eMerge Listings 65-11 Forms for 3270-Display 66.1 Developing Forms for 3270-Display 66-1 66.2 Differences for 3270-Display and i.way-Display 66-2 66.3 Examples of Data Forms for 3270-Display 66-2 66.4 Define the Form 66-4 66.5 Define Form Characteristics 66-8 66.6 Define Blocks 66-9 66.7 Define Field in Block Characteristics 66-13 66.8 Define Form-Dependent Actions 66-20 66.9 Define Entry and Exit Commands 66-21 66.10 Evaluate Initial Form Display 66-22 66.11 Customizing the 3270-Display 66-22 66.12 Offsetting the Block 66-23 66.13 Changing the Number of Columns in a Single-Occurrence Block 66-23 66.14 Changing the Number of Columns Displayed in a Multi-Occurrence Block 66-26 66.15 Displaying Blocks Side by Side 66-27 66.16 Adding Text Around a Block 66-28 66.17 Defining Colors for 3270-Display Forms 66-32 66.18 Creating a Menu for 3270-Display 66-36 Customizing Form Frames 67.1 Frame Elements 67-2 67.2 Using a Custom Form Frame 67-6 67.3 Designing the Form Frame 67-6 67.4 Assigning the Frame to the Application 67.5 Disabling the Command Line 67-10

Chapter 65

Chapter 66

Chapter 67

67-9

Chapter 68
xvi

Documentation and Help Text for 3270-Display Applications

68.1 68.2 68.3

Documenting Knowledgebase Objects 68-1 Help for Fields, Blocks, Forms and Menu Options 68-2 End-User Help for Fields, Blocks, Forms and Menu Options

68-2

Appendix
Appendix a To i.way from Sapiens Workstation a.1 Moving to an i.way Display a-1 a.2 Modifying Sapiens Workstation Forms a-1 a.3 Considerations for Sapiens Workstation Forms a-10 a.4 Differences between i.way and Sapiens Workstation a-15 To i.way from 3270 b.1 Moving to an i.way-Display b-1 b.2 Modifying 3270 Forms b-1 b.3 Considerations for 3270 Forms b-4 Sample Database Used in Queries Using Constructors d.1 What is a Constructor d-1 d.2 Assigning a Foreign Key d-3 d.3 Defining a Constructor as a Subject Constructor d-4 d.4 Implementing Referential Integrity d-9 d.5 Selecting a Value and Zooming in on a Value from the Subject Constructor d-10 d.6 Using Related Values From the Subject Constructor d-10 d.7 Defining Several Subject Constructors for the Same Field d-13 d.8 Introduction to Reengineering d-17 d.9 From Primary Data Objects to Constructor d-17 d.10 From Constructor to Concept Model d-22 d.11 Overview of Reengineering a Constructor to a Concept Model d-23 d.12 Considerations for Reengineering a Constructor to a Concept Model d-24 d.13 Reengineering a Concept Based on an Existing Constructor d-26 d.14 Reengineering a Constructor to a Concept Model Example d-31 d.15 Manipulations During the Reengineering Process d-33 d.16 Reengineering a Concept Design d-37 d.17 Concepts and Designs After Reengineering d-39 d.18 Retreating From Reengineering a Constructor to a Concept Model d-39 d.19 Reengineered Concepts from Previous Versions d-43 Examples of Presentation Components e.1 URL Component e-1 e.2 Script Component e-6 e.3 JavaApplet Component e-13 e.4 ActiveX Component e-21

Appendix b

Appendix c Appendix d

Appendix e

xvii

xviii

eMerge Documentation
Sapiens eMerge is a complete solution, designed to integrate new ebusiness applications with existing assets. Development, deployment and administration of e-business applications are all performed within eMerge. eMerge incorporates an open multi-tier architecture. eMerge comes with guide and reference documentation for development, integration, and administration:

Development and Integration Documentation

Getting Started A general introduction to the eMerge worldincluding the development and runtime environments. A description of i.way and Development Workbench. A brief tutorial showing how to build an eMerge application. A guide for developing eMerge applications, starting from analysis and continuing through design and implementation (via GUI-based modeling). How to define the applications data aspects, presentation and logic. Intended to be used by eMerge application developers using Development Workbench to develop an application accessing Business Integrity Server via i.way and 3270-display. How to develop eMerge-based client software without a familiarity with eMerge, using Business Components. How to expose a set of XML-based services to other parties, as well as invoke XML-based services from other parties. How to access eMerge Web Services. How to use Legacy Adapter for nonintrusive renewal of legacy applications. How to integrate an eMerge application with external data, such as DL/I, VSAM, DB2, SQL/DS, Microsoft SQL Server, and Oracle. A description of the eMerge DBCOBOL language. Intended to be used by COBOL programmers. Describes the DBCOBOL extensions used to access and manipulate an eMerge database using COBOL programs.

Development Guide

Component Integration

Legacy Adapter DBMS Adapter DBCOBOL

xix

DBPL1

A description of the DBPL/1 language. Intended to be used by PL/I programmers as a guide for accessing and manipulating an eMerge database using PL/I programs. PL/I programs referring to an eMerge database mainly serve for data retrieval (though database update is also available).

Administration Documentation
eMerge
Administration How to set up and maintain an eMerge database. How to configure and manage Business Integrity Server under each supported environment. How to configure and manage eMerge Client, including i.way performance. How to set up sessions for accessing Business Integrity Server via i.way and Development Workbench. How to use Connection Pool Manager and context switching with Business Integrity Server. Intended to be used by system personnel (administrators, system programmers, etc.). There is a manual for each supported platform.

Business Integrity Server

Installation Message Report How to install Business Integrity Server under each supported environment. There is a manual for each supported platform. A listing of the messages that are generated by Business Integrity Server, and their explanations.

eMerge Client
Installation How to install eMerge Client. How to set up sessions for accessing Business Integrity Server via i.way and Development Workbench.

xx

Reference Documentation
Form Reference A reference of eMerge forms, including the access to the form, the purpose of the form, its categories, and a description of all the fields (with their popup menus) and form actions. The forms are used by:

eMerge application developers using Development Workbench to develop an application accessing Business Integrity Server via i.way and 3270-display developers using Business Components, XML Messaging, Legacy Adapter, or DBMS Adapter administrators of Business Integrity Server

General Reference

A general reference, including:

Descriptions of Modeler, commands, rule and query syntax, and DOM extensions for use by eMerge application developers using Development Workbench to develop an application accessing Business Integrity Server via i.way and 3270-display. Descriptions of interfaces and methods for manipulating data in the Business Integrity Server database for use by developers using Business Components. Descriptions of commands and rule syntax for use by developers using XML Messaging. Descriptions of commands for use by developers using Legacy Adapter. Descriptions of commands for use by developers using DBMS Adapter. Descriptions of commands used by Business Integrity Server personnel (administrators, system programmers, etc.). Information for all supported environments is covered. Descriptions of Business Integrity Server utilities. Information for all supported environments is covered.

Documentation Conventions
<name> Angle brackets are used for the following:

a variable representing the full path to a file (i.e. drive and directory name); e.g. <sapiens> to represent c:\sapiens
xxi

a string variable; e.g. <dbname> around a continuation tag in a flow or syntax around the name of a key on the keyboard; e.g. <Enter>, <F3>

word display

This font indicates something you type in on the keyboard or indicates listings or text generated by the system. The arrowhead identifies a menu option or a node in a tree form. Name is the name of a pull-down menu or a node. Item is the menu option or subnode. This font indicates platform-dependent information. Italic indicates the first time a term is being introduced. Bold is used for file and directory names and for emphasis.

Name > Item

Platform italic bold

Syntax for Commands, Rules, Queries and Utilities

The conventions described here are used in the following types of syntax diagrams:

for commands issued from within an eMerge session for rules, queries, and DBCOBOL and DBPL1 statements for Business Integrity Server utilities issued under i5/OS

General Reference Conventions

Read the syntax diagrams from left to right, and from top to bottom, following the path of the line.

Line Types

Indicates the beginning of a statement.

Indicates the beginning of a clause (part of another syntax diagram) or that the syntax is continued from the previous line.
xxii

Indicates the end of a clause (part of another syntax diagram) or that the syntax is continued on the next line.

Indicates the end of a statement.

Repeat Arrows
An arrow returning to the left indicates that an item can be repeated. If a separator is needed, it appears on the repeat arrow.

Any syntax included in the repeat arrow follows all the normal syntax rules described here.

Punctuation Marks
If punctuation marks, parentheses, arithmetic operators or such symbols are shown, they must be entered as part of the syntax.

Parameters
Required items (e.g. keywords, variables) appear on the main path:

If you can choose from two or more items, they appear vertically in a stack. If the items in the stack are optional, the stack appears below the main path:

xxiii

If you must choose one of the items in the stack, one of the items in the stack appears on the main path:

Keywords and Variables

z/OS, i5/OS Keywords appear in uppercase or mixed case (e.g. MINimum). All uppercase characters in keywords must be typed as shown (i.e. MIN must be typed). You can omit the characters in lowercase. Variables, representing user-supplied values, appear surrounded by angle brackets (e.g. <choice1>). Keywords and variables are separated by a blank. HP-UX, Linux, Windows Keywords appear as bold letters (for example create) and must be specified exactly as shown except in cases of mixed lettering (e.g. dataset), where only the characters in bold type must be specified and you can omit the non-bold. Variables, representing user supplied values, appear in italicized letters (e.g. choice1). Keywords and variables are separated by a blank space. The description of the syntax indicates where a blank space is not allowed.

Expressions
Expressions denote a further breakdown of the syntax (i.e. displayed subsequently). Braces ({}) around a string in a syntax diagram denote such an expression. Expressions can be common to more than one statement or can be specific to a particular statement.

xxiv

Defaults
The default is what occurs if no value is supplied for the parameter. Defaults are shown in: z/OS, z/VM, i5/OS HP-UX, Linux, Windows bold underline

If there is an initial setting on entering an eMerge session, this is noted in the command description.

xxv

xxvi

Part A

Introduction

About This Guide

This guide is intended to be used by application developers using eMerge to develop an application. The guide assumes that the Getting Started manual, including the tutorial, has been read. This manual contain the following information:

Part A Introduction
A general introduction to eMerge. A description of the eMerge data structures and application development.

Part B Data
A description of eMerge data structure development. How to build and change an application data structure, using the concept model and the constructor path via Development Workbench.

Part C Logic
A description of how to create the eMerge application logic, using the rule model. How to define eMerge rules using the eMerge rules.

Part D Accessing the Data

A description of how messages are used to access the data. A description of operations and how to define them.

Part E Presentation
A description of the application presentation and how to create the forms (e.g. data forms and menus) needed to support an application.

Part F Help for Applications

A description of how enter documentation for knowledgebase objects.

Part G Reports and Queries

A description of the different facilities available to create reports and queries.

Part H External Programs

A description of how to use external programs with eMerge.

Part I Multilingual Applications

A description of the multilingual feature, enabling you to develop an application to be run in more than one language.

Part J Change Management

Some things the developer should know, when change management is used at the site.

Part K Development Privacy

A description of what the developer needs to know if development privacy is used at the site.

Part L eMerge Applications via 3270-Display

Intended to be used by eMerge application developers preparing applications that are accessed via 3270 emulation.

Appendix a, To i.way from Sapiens Workstation

Describes how to modify an existing set of application formsforms that were developed and accessed via Sapiens Workstation and are to be accessed via i.way. Contains the modifying procedure for Sapiens Workstation forms and a set of considerations for Sapiens Workstation forms.
4

Appendix b, To i.way from 3270

Describes how to modify an existing set of application formsforms that were developed and accessed via 3270 terminals and now are to be accessed via i.way. Contains the modifying procedure for 3270 forms and a set of considerations for 3270 forms.

Appendix c, Sample Database Used in Queries

The database structure and data used in the query examples in this guide.

Appendix d, Using Constructors

A description of constructorsthe tool used in earlier versions to create data structures (i.e. composites, classes and fields). A description of the reverse engineering processhow to create concepts via Modeler based on an existing constructor definition.

Appendix e, Examples of Presentation Components

Examples of how to use components.

Chapter 1 eMerge Application Development

1.1

Building an eMerge Application

To build any eMerge application (e.g. a human resources management system, a sales management system), you must identify the data objects in the organization. A data object is anything about which information needs to be stored (e.g. employees, customers). The physical data can be held within eMerge datasources (DB1) or externally in various formats (including legacy applications). The objects are defined and stored in an eMerge knowledgebasethat belongs to a particular eMerge moduleas logical objects that access physical data. Users or groups of users (i.e. worlds) are granted access rights to all or parts of the applications. The logical objectsincluding applications, modules, composites (the primary data object), and application users and worldsare defined and stored in the eMerge Catalog. More than one eMerge Catalog can be defined for a site.

1-1

eMerge Application Development Building an eMerge Application

If the applications being built are:

a human resources management system a sales management system

the following shows the modules, their relationships to the physical data and the applications, and the users and worlds that have access to some or all of the applications:

1-2

eMerge Application Development Data Structure in eMerge

1.2

Data Structure in eMerge

The primary logical data object in eMerge is a class within a composite. A composite is a hierarchical tree of related classes composed of one root class and a number of dependent classes. Any class within the composite hierarchy can be a parent of dependents. A class is described by a collection of attributes which, in eMerge, are known as fields. A field is the smallest unit of data in the knowledgebase. An occurrence describes one instance of a class; for example, an occurrence of employee is Abigail Smith.

1-3

eMerge Application Development Data Structure in eMerge

A typical composite might have the following structure: root class

dependent classes fields

2
Class 1 is the parent of Class 2

Example: A human resource management system includes an Employee composite. Each employee has benefits, a history (including work experience and medical history), children, and other data. The following diagram illustrates how this can be represented as a composite containing classes: Employee Employee

Child

Benefits

History

Work Experience

Medical History
date problem treatment

The Employee composite has the Employee class as the root class. The Child class is a dependent class. Note that there can be more than one child for each employee.

1-4

eMerge Application Development Data Structure in eMerge

The History class is a dependent class and has dependent classes of its own: Work Experience and Medical History. Thus, History is the parent of Work Experience and Medical History. The Medical History class contains the date, problem and treatment fields. Abigail Smith, an occurrence of Employee, may have children: Michael Smith, and Jonathan Smith. Michael Smith and Jonathan Smith are each occurrences of the Child class.

Relationships Between Objects

In addition to defining the data objects (i.e. classes) when building an application, you must also define the relationships between the objects. A relationship can be between a parent and its dependent, between two parents, or between two dependents. Part of the definition of a relationship is its cardinality, the number of occurrences of each object in the relationship relative to the other object in the relationship. That is, is the relationship one-to-many, many-toone, one-to-one, or many-to-many. Example: In the Employee composite, the root class Employee is related to many occurrences of the Child class (i.e. a parent can have many children), but to only one occurrence of the Benefits class (one-toone). One-to-Many or Many-to-One Usually, a task can be done by many employees. Thus, the task employee relationship is one-to-many. A one-to-many and a many-to-one relationship is, in essence, the same relationship, viewed from a different position. Thus, when the relationship is looked at from the point-of-view of the employees and the task they work on, there is a many-to-one relationship. One-to-One A task has only one manager. The taskmanager relationship is one-toone. (It could also be defined by including the details about the manager in the Task class.) An employee can work on many tasks and a task can be worked on by many employees. Thus, the employeetask relationship is many-tomany.

Many-to-Many

1-5

eMerge Application Development Data Structure in eMerge

Identifying OccurrencesKey Fields

Each class occurrence is identified by a unique identifierthe key. The identifier is created from one or more fields. The fields used as the identifier, i.e. key fields, must be defined contiguously before any other fields in the class. Example: There must be a unique way to identify each employee in the human resource management system. The Employee class uses the employee-no field as its identifier. A particular employee number can be used only onceone for each employee. The identifier (key fields) of the root class uniquely identifies the root class, as well as uniquely identifying the composite. The identifier of a dependent class consists of the concatenation of the key fields of all parent classesthe path from the root class to the immediate parent plus its own key field. The following shows a composite with the key fields shaded: Composite B root class key dependent class 1 key field field field field field

dependent class 2 k e y field

multiple class occurrences

dependent class 3 key field

The identifier for dependent class 3 consists of a concatenation of these key fields:

the root class key field class 2 key field (here made up of two fields) its own key field (from class 3)

1-6

eMerge Application Development Modeling Your Application

Example: In the Employee composite below, the identifier for a particular child is Employee ID (the path) plus Child ID (its own key field). Employee Employee
Employee Employee Name ID

Child
Child ID

Child Name

Address

History

1.3

Modeling Your Application

An eMerge application is built via a graphical model. The graphical model is built using Modeler. Modeler is one of the tools provided within Development Workbenchthe eMerge development environment. The graphical model is used to generate a default application, including input forms, flows and the necessary internal data structures to support the application. Using Modeler facilitates an iterative development approach, based on user feedback and design considerations. You use Modeler to create: a concept model a rule model Modeler enables the graphical concept model to be exported to any Unifed Modeling Language (UML) tool that supports XMI 2.1. UML is the industry standard modeling language; it is the set of notations, models and diagrams used when developing object-oriented (OO) systems. UMLlike Modelerenables the analyst to:

build and maintain an organizations application model define the behavior of significant parts of that application define the relationships between those parts

Models can be exported to XMI files when in any of the modeling stages (analysis, design and implementation). Designs created when a concept is in the design or implementation stage are also exported. When concept models are exported to XMI, all associated rules are exported with them.

1-7

eMerge Application Development Modeling Your Application

Concept ModelModeling the Data

You model the data aspects of the organization via the concept model. The concept model is an extended version of the basic ER (entity relationship) diagram made up of data objects, called concepts. In addition to modeling the entities that comprise the organization, and the relationship between these entities, the concept model provides you with concept types that mirror the real world. You develop the concept model through controlled analysis, design and implementation stages. Example: The following model shows the Employee concept with its related concepts:

When you use one of these concept types, defaults are set which are specific to the type of the concept. The concept model results in the following:

Definitions, specific to the type of the object, are automatically assigned for you, ensuring accuracy and simplifying the modeling process. The model is an accurate representation of the real world. It is easy to read and develop.

Rule ModelModeling the Logic

You model the application logic via the rule model. The rule model is a graphical description of the rulesets and rules in an application. You use the rule model for creating rulesets and rules, as well as for changing existing rulesets and rules. A rule is part of a ruleset (i.e. a ruleset is specified via one or more rules). A ruleset is usually attached to a triggering object. The triggering object can be almost any object within the eMerge knowledgebase (e.g. a
1-8

eMerge Application Development Modeling Your Application

concept). The triggering object can have more than one ruleset attached to it. You develop the rule model through controlled analysis, design and implementation stages. You can use the rule model independent of a concept model. Use the rule model to review and extend existing rulesets and rules created in the past, as well as to create new rulesets and rules. Event Driven Any change in the state of the triggering object (i.e. user action or data update) triggers the rulesets. When a ruleset is triggered, the rules in the ruleset are validated to determine if they are relevant to the situation, and if relevant, they are executed. A complete business rule is held in a ruleset. Once a ruleset has been created, it can be used repeatedly, wherever it is needed. The rule model works according to the positive thinking inherent within eMerge business rules. Only the primary situation and its consequences need be defined. Related situations are automatically inferred. This leaves the developer free from having to code related situations and their consequences. positive thinking in eMerge business rules
situation d situation c situation b situation a * consequence d consequence c consequence b consequence a *

Reusability of Rules Positive Thinking

automatically inferred defined

primary

Example: A business rule must be defined such that the number of items ordered by a customer must be reflected immediately in the inventory. The primary situation is the subtraction of the quantity of items from the inventory when an item is ordered by a customer. This results in the following set of automatically inferred consequences:

1-9

eMerge Application Development Application Development Stages

Situation

Consequence

Changing the number of items Number of items stored in the inventory changed ordered by the customer accordingly Change an ordered item to another item Deleting an item from the order Deleting the whole order Number of items in the inventory is increased for the cancelled item and decreased for the newly ordered item Number of items in the inventory is increased for the deleted item Number of items in the inventory is increased for all the items in the order

1.4

Application Development Stages

eMerge application developmentdone via concept models and rule models is done through controlled, distinct development stages: analysis, design and implementation. Thus, developing an eMerge application means building the application via a graphical model that is taken from analysis to design to implementation. Each object (concept or rule) in a model is in a clearly defined development stage. The development stage is represented in the model by the color and/or pattern of the symbol in the model, so you can tell at a glance how development is progressing. Each model can be developed independently. In a single model, you can have objects at any of the development stages. The concept and rule models together provide an integrated working application.

Concept Model
Analysis For the concept model, you create the extended entityrelationship diagram that describes the concepts in your organization, and how they interrelate. For each concept, you define the concept via its name, its type (entity, weak entity etc.) and how it is associated with other objects. Specific details about individual concepts (such as the rules that the concept must obey) can either be added at this point, or later, during design and implementation. Data structure development within eMerge consists of determining and defining the following: 1 The participating objects; i.e. classes
1-10

eMerge Application Development Application Development Stages

2 The hierarchy of the classes within a composite: Is the class a root class or a dependent class? 3 The associations between classes: one-to-many many-to-one one-to-one many-to-many 4 The fields that comprise the class: identifier for a root class: key field for a dependent class: path plus key field name field attribute fields Design When you advance the development stage of an object to the design stage, the default designs necessary to reflect your analysis are created. The designs are based on the information you entered during the analysis stage. Full referential integrity is automatically ensured between designs. The designs for concepts are readable. You can modify the designs and add new designs as you see fit. Implementation On implementation, the concept model is used as input to generate the data structures stored in the knowledgebase. Based on the concept definitions, and the associations defined between them, not only are the required data structures created, but part of a complete application is generated. The application generated covers the three necessary aspects of a complete application: data, logic and presentation. Data For each concept, a class within a composite is generated. If the concept is defined as a root concept (i.e. an entity), a new composite is generated with a root class. If it is defined as a dependent concept (e.g. a weak entity), a class is generated in an already existing composite. The data for the composite can be stored permanently in a physical database or temporarily in task memory. Logic The operation needed to retrieve and update the data is generated. All the fields that comprise the concept are in the operation. Thus, all the information that makes up each occurrence can be accessed. Rules are automatically generated to maintain referential integrity between the fields within its classes. Thus, when an occurrence of a parent is deleted, all related occurrences of its dependent classes are
1-11

eMerge Application Development Application Development Stages

deleted as well. Conversely, before a dependent class occurrence is inserted, the related parent class occurrence must exist. Presentation The data forms (representing the classes) needed to populate the database with the application data, and a basic flow between the forms are generated. The data forms are for a singleoccurrence form and for a multi-occurrence form. The following diagram shows what is generated when implementing a concept: Presentation Data composite multi-occurrence form single occurrence form Logic operation hidden rules for referential integrity

Concept

implement

root or dependent class fields

Rule Model
Analysis You build the rule model by:

determining the business rule and defining it as a ruleset documenting what the ruleset is intended to do defining the rules that make up the ruleset determining the target object if the rule needs one determining the nested rulesets if there is a need documenting what the rule is intended to do

Design

A rule is automatically advanced to the design stage as soon as you begin:

writing the rule specification using Rule Editor assigning any rule options entering any error messages

1-12

eMerge Application Development Data Access and Manipulation

Implementation

All the rules of a ruleset are implemented when they are compiled. Test the ruleset by testing the triggering object. For example, if the rulesets triggering object is a concept, testing the implemented concept includes testing its rules.

1.5

Data Access and Manipulation

Accessing the Data via Messages
Data within an application must be accessed; i.e. retrieved or updated. The integrity of the data is maintained by the application. To access the data, messages are sent to the Business Logic Processor. The Business Integrity Server retrieves or updates the appropriate data occurrences based on the message. In eMerge, there are the following types of messages: Operation Stored in the knowledgebase, an operation is an input structure with an operation code and destination target class. The operation accesses the fields in the target class for viewing or for update. Included in the operation definition are the fields upon which the operation is performed. The developer can define any operations needed for retrieval or update by including as many fields as needed. A query is a request for information, and a set of instructions on how to select, format and display that information. Once the data is accessed by the query, the query can:

Query

send an operation which can do any update or retrieval needed, based on specific criteria produce simple reports, including statistical functions (totals, averages etc.) copy data to an external file, based on specific criteria

Program

External programs (e.g. COBOL or PL1 or C, depending on the platform) can be used for complex reporting and data manipulation. DBCOBOL and DBPL1 are 4GL extensions to COBOL and PL1 to allow COBOL or PL1 programs to access or update the data. Once the data is accessed by the external program, the external program can do the following:

perform any update or retrieval needed send an operation which can do any update or retrieval needed
1-13

eMerge Application Development Data Access and Manipulation

produce reports copy data to an external file, based on specific criteria

These programs can be executed either online from within eMerge, or in batch mode externally.

Message Results
Operations can access or update the data, and produce listings (used mostly for development). Queries or programs can access or update the data, and produce listings with or without using operations. The online interaction between the end user and the database is done via forms. Forms can handle all message typesoperations, queries, and programsto access or update the data.

Note that any update or retrieval via an operation triggers any rules attached to the related triggering objects.

1-14

eMerge Application Development Presentation

1.6

Presentation
Forms and the flow between the forms make up the presentation. The user of an eMerge application enters and retrieves data via forms. Forms types are:

data menu tree compound select and detail

Templates and form components expand the presentation functionality.

Data
Data forms are used to enter data. You create your applications by entering the relevant definitions into data forms. The end user enters data into the forms you create. Example: single occurrence form The following are two forms for the Employee concept:

multioccurrence form

1-15

eMerge Application Development Presentation

Menu
In a well designed application, there is a logical order or flow for moving from one form to another. The movement from one form to the next can be directed by a menu. The menu is a list of options that are used to access forms or to perform actions:

Text of Option Icon of Option

The menu form consists of a menu name and number, options, and action buttons. Each option can be displayed with an icon and text describing the option. A menu option is selected by clicking the icon or the text of the desired option.

Tree Compound
A tree compound form consists of two frames: One frame contains the tree form (i.e. the tree control) and one contains a data form. The tree compound form is used as the "top form" for an application. A list of items is presented to the end user in a tree. The user can expand or contract the nodes to view or hide a list of sub-items.

1-16

eMerge Application Development Presentation

Tree Form

Data Form

Tree Compound Form You specify the layout for the forms in the tree compound form: horizontalthe called forms are placed one above the other. verticalthe called forms are placed alongside each other.

Select and Detail Forms

For any relationship between two entities (including a dependency relationship), the key field and the name field of one entity can be used to access data from the other entity.
1-17

eMerge Application Development Presentation

Select Form

A select form is a multiple occurrence data form. On accessing the select form, all the existing values for the particular field are displayed. The user can select a value and return to the calling form.

Detail Form

A detail form is a single occurrence data form. On accessing the detail form, details of the occurrence having the particular key field or name field are displayed.

Template
To help create all the forms needed for an application, use a form template. A template is a model form on which you can base application forms. Each form that has a template assigned starts off with the options assigned to the template. You may then modify the individual form when and where necessary.

1-18

eMerge Application Development Presentation

Using a template for forms:

Enables all forms to have the same "look and feel" with minimum effort; i.e. templates can be used to set a standard look for an application. Greatly reduces the number of modifications needed to make to individual forms, therefore speeding up the development process. Enables leveraging the work put in to create and define blocks, operations, form actions, color, background, font, etc. from one form to another.

Form Components
Form components enable:

A form flow that goes from one module to another modulelinking a form in one module with a form in another module. Defining a top form for a user.

A form (i.e. the calling form) in one module (i.e. the source module) can be linked to a form (i.e. the called form) in another module (i.e. the target module). The end user "goes" from the calling form to the called form via any of the usual ways of invoking a form by another form, including a select form, a form action, or a popup menu. Example: The WT_ORDER_SELECT form in the figure below is defined in the WT module. The values that can be selected in the WI Customer Id field come from a select form in the WB module.

1-19

eMerge Application Development Presentation

Clicking the Customer form action on the WT_ORDER_SELECT form opens the fhe WB_CUSTOMER form in the WB module:

1-20

Part B

Data

Chapter 2 Analysis StageBuilding a Concept Model

2.1

Concept Model
Modeler creates default designs and generates an implemented application based on the concept model you build during analysis. Thus, the way in which you define the concepts for your concept model is important. The model should reflect, as much as possible, your organization. If you pay close attention to building a model that accurately represents your application, you can rely on the default designs and implementations created by Modeler. To define concepts correctly during analysis, you must have a clear understanding of how the organization functions. You must understand what role each concept plays in the organization, and what the organization does with each piece of data. In other words, during analysis, you must decide what is a concept and what is merely an attribute of a concept. Once the concept is identified, you must correctly identify its type. The information you define about each concept at analysis includes the following:

name of the concept type of concept: entity, weak entity, association, document, or domain its parent or parents its relationship with its parent concepts: cardinality and probability its fields its rules

In a concept model, each concept is in a clearly defined development stage: analysis, design or implementation. In a single concept model, you can have concepts at all of these development stages. The current stage of a concept is represented by the color of the concepts graphic symbol in the model, so you can tell at a glance how development is progressing. When a concept is in the analysis stage, its default symbol in the model is blue with no pattern.
2-1

Analysis StageBuilding a Concept Model Inserting a New Concept Model

2.2

Inserting a New Concept Model

1 On the Data tab of the Navigation Pane, right-click the Models node. A pop-up menu is displayed:

2 Choose New Model. The New Concept Model form is displayed:

3 Specify the model name in the Model textbox. 4 Select a template to be used for the model from the Form Templates listbox that lists forms created from this model (both default forms and user-defined forms). 5 Select the rangeset for the model in the Rangeset ID listbox.

2-2

Analysis StageBuilding a Concept Model Inserting a New Concept Model

The Rangeset ID is the identifier of the rangeset used by Modeler to assign the Constructor Number, the number that uniquely identifies the model in the knowledgebase. Ask your Administrator for which Rangeset ID to use. The rangesets are defined by the Administrator. You must be assigned as an allowed user for the rangeset you choose. 6 Select the Complexity for the model. The complexity is the number of dependents a root concept has:
VERY COMPLICATED COMPLICATED FLAT

One hundred or more dependents.

Ten dependents.

Usually no dependents.

Select the complexity for the majority of the root concepts in the model. The complexity for a particular root concept can be overridden.

If your model has a number of root concepts with one complexity (e.g. FLAT) and others with another complexity (e.g. COMPLICATED): Select one complexity for the model (e.g. FLAT) and insert the first group of concepts. Then, change the complexity (e.g. COMPLICATED) and insert the second group of concepts.

7 Click Apply to create the new model.

2-3

Analysis StageBuilding a Concept Model Reviewing and Modifying an Existing Model

8 Click the OpenModel button to display the new model in the work pane:

2.3

Access ViewOptionsSymbolsDisplay to change the color and pattern for concepts in the concept model.

Reviewing and Modifying an Existing Model

1 On the Data tab, expand the Models node and right-click (or double-click) the model you want to open. A pop-up menu is displayed.

2-4

Analysis StageBuilding a Concept Model Type of Concept

2 Choose Open. The model appears in the work pane.

2.4

Type of Concept
The concept types are as follows:

entity weak entity document domain association

Weak entity, document, and domain are special cases of the entity concept. Example: In a school system, the concept Child would be an entity and the Parent of the child would be a weak entity dependent on Child. In a personnel department application, the Employee is the entity and the Child is a weak entity dependent on employee. A description of the concept types follows.

Entity
An entity is a data object that serves as the root in a hierarchical tree of related concepts. It is defined with a unique identifier (i.e. the key field) and descriptive fields supplying additional details. An entity is an important and distinct part of the organization. Example: For a personnel department, the Employee is an entity. The employee is important to the personnel department. Usually, an entity is not dependent. However, you can define an entity that is in a dependency association with another entity (an entity with a parent). Example: For accounts, the Bank and the Branch of a bank are entities. They are both important to the organization. However, you may want the Branch entity to be dependent on the Bank entity, so that the key for the branch occurrence consists of two fieldsthe code for the bank and the branch number.

2-5

Analysis StageBuilding a Concept Model Type of Concept

Weak Entity
A weak entity is a dependent data object. It must be defined with at least one field. A weak entity is a part of the organization that is solely dependent on its parent concept for its existence, and is of relatively less importance to the organization. Example: In the personnel department application, the children of an employee are modeled as the weak entity Child. The children are only of interest because their parent is an employee.

Document
A weak entity is a dependent data object that contains multiple lines of text. A document contains a description of its parent concept. Like the weak entity, the document concept has no importance within the organization without the parent concept. A document cannot be a parent concept. Example: In the personnel department application, the document Medical Detail appears as a dependent of the weak entity Medical. This contains any descriptive text which might be needed with a record of medical information about the employee.

Association
An association defines a direct relationship between concepts (normally two entities). The concepts associated by an association are called the parent concepts of the association.

Note: the integrity of data for an association must be maintained by the application.

An association between a concept and itself is a recursive association. Example: In the personnel department application, there is an association between the Employee and the Article the employee has published. The association is Authorship. It is many-to-many because an employee may have several articles, and a given article may be coauthored by several employees. The Article concept is not dependent on the employee entity, because the organization might be interested in publications resulting from work done in the organization, even after the authors are no longer employed.

2-6

Analysis StageBuilding a Concept Model Inserting a Concept

An association can have both its own identifier (as part of its key) and its own non-identifying fields. Example: There is another association in the personnel department applicationthe Manager association between boss and employee. This association is a recursive association because a boss can also be an employee with a boss.

Domain
The domain concept describes a field of one or more other concepts. When you associate a field with a domain, the field inherits the characteristics of the domain: Data Type, Size etc. When you change the characteristics of a domain, the characteristics of all fields associated with that domain are changed accordingly. You can define a domain for the following purposes:

For a generic field definition that can be applied to multiple fields in multiple concepts For possible value restrictions for multiple fields in multiple concepts To join a field that already exists in the knowledgebase, but was not created via Modeler.

See "Domain Concept" on page 3-7 for more information.

2.5

Inserting a Concept
For specific instructions on inserting an entity, weak entity, document or association in a model, refer to the subsections beginning on page 2-10. For instructions on inserting an entity in a dependency association with an existing parent, refer to page 2-18. You cannot insert a domain into the model since it does not have a graphical representation. For details on inserting and using domains, see "Domain Concept" on page 3-7. For a root concept (an entity) 1 Click the icon, and choose the location for the graphic symbol in the model. A dialog box opens to accept values for the parameters needed to define this type of concept. 2 Define the concept parameters. The parameters that define the concepts that can appear in the model are shown in the following table. Some of

2-7

Analysis StageBuilding a Concept Model Inserting a Concept

these parameters are specific to certain types of concepts and some of these parameters have default or fixed values on entry to the dialog box. For a dependent concept (weak entity, document, association, or entity with a parent 1 Click the parents, click the appropriate icon and choose the location for the graphic symbol in the model. A dialog box opens to accept values for the parameters needed to define this type of concept. 2 Define the concept parameters. The parameters that define the concepts that can appear in the model are shown in the following table. Some of these parameters are specific to certain types of concepts and some of these parameters have default or fixed values on entry to the dialog box. Parameter Name Link Description Cardinality Defined for which concepts All concepts Entity with a parent, weak entity, document, association Recursive association Entity with a parent, document Weak entity, association, recursive association Probability Significance Prefix Weak entity, association, recursive association Association and recursive association Recursive association Optional Must enter None (fixed) As required (defaults given) As required (defaults given) Must enter before moving the concept to design or implementation Must enter before moving the concept to design or implementation Action required Must enter

Name

Each concept must have a name that is unique among all functions and concepts in the database.
The name given to a concept is generally given in the singular: for example, CHILD rather than CHILDREN. If there are multiple instances, this is indicated by setting its cardinality to many.

If you are including an existing concept and want to choose from a list of existing concepts, click the Find button. The Model Selection dialog box opens. Via the Concepts button, you can open the Concept Selection

2-8

Analysis StageBuilding a Concept Model Inserting a Concept

dialog box to choose from a list of all existing concepts that meet the following criteria:

They are of the same type They have the same parent or parents They do not yet exist in the current model

Link Description

A description of the link between the parent and dependent concepts. This description can be displayed along the line connecting the concept to its parent. Use it to make the model more readable. For a recursive association, this description is mandatory.

Cardinality

Defines how an association links two parent concepts. The cardinality and probability are used to define the link between a concept and its parent. One For an association, there can be only one occurrence of a parent concept for each occurrence of the other parent concept. For a weak entity, the parent can only have one occurrence of the weak entity. Example: There is one SPOUSE for each EMPLOYEE.

Many For a weak entity, the parent can have many occurrences of the weak entity. Example: There can be many PATENTs held by each EMPLOYEE. For an association, there can be many occurrences of a parent concept for each occurrence of the other parent concept. Example: In an ORDER-ITEM association, a single order can contain many ITEMS and, conversely, an ITEM can be ordered in different ORDERS. Thus, each parent concept is assigned a cardinality of Many. Example: A CUSTOMER-ORDER association can be created between the and CUSTOMER entities. Each ORDER can have only one CUSTOMER, but a CUSTOMER can have many ORDERS. Thus, the CUSTOMER parent concept is assigned a cardinality of 1, while the ORDER parent concept is assigned a cardinality of Many.
ORDER

Probability

Defines, for a given association, how likely it is that at least one occurrenceof the given associationin a certain direction does exist. The cardinality and probability are used to define the link between a concept and its parent. Mandatory Indicates that at least one occurrence must exist.

2-9

Analysis StageBuilding a Concept Model Inserting a Concept

High Indicates that there is a good chance that at least one occurrence exists. Low Indicates that there is little chance that at least one occurrence exists. Significance Significance is relevant only to associations and recursive associations. This is an indication of the main parentthe parent to whom the existence of the association is more important. It is the parent from which you will be more likely to look at the association. Prefix For a recursive association, you must provide a different prefix for each side of the association. The prefix is a short description you assign. Business Integrity Server uses the prefixes to avoid generating duplicate names when the names are based on the name of the parent (e.g. classes names), as these would otherwise be ambiguous.

Inserting an Entity
Insert a new or existing entity into a model by choosing its location and giving its name. For instructions on inserting an entity with a parent, see page 2-18. 1 Click the Entity button or choose InsertEntity. The mouse pointer changes to . Click the location in the model where you want to place the entity. If, at this point, you change your mind and decide not to insert the entity, press <Esc> or click the Abort button to get out of concept insert mode. 2 A rectangle representing the entity appears in the model, and the Entity dialog box opens:

2-10

Analysis StageBuilding a Concept Model Inserting a Concept

3 Choose New or Include. This switch indicates whether you are creating a new entity, or including an entity that already exists. 4 Enter the Entity Name. 5 Click OK. 6 The entity is displayed in the model:

Inserting a Weak Entity

Insert a new or an existing weak entity into a model by indicating its parent, choosing its location, and entering its name. Describe its association with its parent by specifying its cardinality and probability. 1 Select the parent concept on which the weak entity depends. If you are inserting a weak entity that already exists, it can only be inserted under the same existing parent concept. 2 Click the Weak Entity button or choose InsertWeak Entity. The mouse pointer changes to . Click the location in the model where you want to place the weak entity. If, at this point, you change your mind and decide not to insert the weak entity, press <Esc> or click the Abort button to get out of concept insert mode.

2-11

Analysis StageBuilding a Concept Model Inserting a Concept

3 A trapezoid representing the weak entity appears with a line connecting it to its parent, and the Weak Entity dialog box opens:

4 Select New or Include. This switch indicates whether you are creating a new weak entity, or including a weak entity that already exists. 5 Enter the Weak Entity Name. 6 Enter a Link Description if you wish. 7 Select the appropriate values for Cardinality and Probability. 8 Click OK. The weak entity is displayed in the model, attached to its parent entity. If you typed a link description, this appears along the line connecting the weak entity to its parent.

2-12

Analysis StageBuilding a Concept Model Inserting a Concept

Inserting a Document
Insert a document the same way you insert a weak entity, except that for a document, the cardinality is always many. 1 Select the parent entity, weak entity or association on which the document depends. If you are inserting a document that already exists, it can only be inserted under the same existing parent concept. 2 Click the Document button or choose InsertDocument. The mouse pointer changes to . Click the location in the model where you want to place the document symbol. If, at this point, you change your mind and decide not to insert the document, press <Esc> or click the Abort button to get out of concept insert mode. 3 A parallelogram representing the document appears with a line connecting it to its parent, and the Document dialog box opens:

4 Choose New or Include. This switch indicates whether you are creating a new document, or including a document that already exists. 5 Enter the Document Name. 6 Enter the Link Description if you wish. 7 Click OK.

2-13

Analysis StageBuilding a Concept Model Inserting a Concept

The document name appears on the parallelogram in the model. If you typed a link description, this appears along the line connecting the document to its parent.

Inserting an Association
Insert an association the same way you insert a weak entity except that an association has two parents (which in a recursive association are actually the same concept). To create an association among three or more concepts, define associations between pairs of concepts, and then define associations between the associations or between an association and another concept. 1 Select one or two parent concepts, by clicking a parent and then shiftclicking the other parent. If you choose only one parent, Modeler only allows you to define a recursive associationan association between a concept and itself. If you are inserting an association that already exists, it can only be inserted under the same existing parent or parents. 2 Click the Association button or choose InsertAssociation or InsertRecursive Association. The mouse pointer changes to . Click the location in the model where you want to place the association.

2-14

Analysis StageBuilding a Concept Model Inserting a Concept

If, at this point, you change your mind and decide not to insert the association, press <Esc> or click the Abort button to get out of concept insert mode. 3 A hexagon representing the association appears with lines connecting it to the parent concept or concepts, and the appropriate Association dialog box opens. The Recursive Association dialog box is identical to the Association dialog box, except that it has the Prefix text boxes.

4 Choose New or Include. This switch indicates whether you are creating a new association, or including an association that already exists. 5 Enter the Association Name. 6 Select the appropriate Cardinality and Probability option buttons for each side of the association. 7 Select the appropriate Significance option button. Significance is the indication of the main parentthe parent to whom the existence of the association is more important. It is the parent from which you will be more likely to look at the association. To advance the development stage of the association to the design stage, you must designate one of the parent concepts as the main parent. 8 Enter the Link Description for both sides of the association. For a recursive association, this step is mandatory. For a non-recursive association, it is optional and you can enter a link description for only one side of the association.

2-15

Analysis StageBuilding a Concept Model Defining a Dependency Association between Entities

9 For a recursive association only, type a different prefix into the Prefix text box for each side of the association. You cannot advance the recursive association to a higher stage, unless you supply both prefixes. The Prefix is a short description you define. This description is used by Business Integrity Server to maintain the internal integrity of your model. 10 Click OK. The association is displayed in the model.

2.6

Defining a Dependency Association between Entities

A dependency association is an association of an entity with another entity (the parent entity) for the purpose of key inheritance (the concatenation of the parent concepts key with the key of the dependent concept) in the non-parent (dependent) entity. The dependent entity is also known as an entity with a parent.

Creating a dependency association does not change the parent entity.

When the dependent entity is implemented, Modeler does not create a hierarchical structure. The dependent entity is implemented with the parent entitys key concatenated to its key. Example: In the organization, the BRANCH entity is dependent on the BANK entity for its key. That is, to determine the branch an account is in, you need both the bank number (the key to the BANK entity) and the branch number (the key to the BRANCH entity). Defining a dependency association between the BRANCH entity and the BANK entity, where the BRANCH entity is the dependent entity, concatenates the BANKs key to the BRANCHs key. You can create a dependency association where the parent entity is a dependent entity in a different dependency association.

2-16

Analysis StageBuilding a Concept Model Defining a Dependency Association between Entities

Example: If there is an association between a concept and the BRANCH entity (described in the previous example), a validation on the bank number is done in the BRANCH entity and not in the BANK entity. A dependency association between two entities can be established in two ways:

If both entities already exist in the model. If the dependent entity does not yet exist in the model.

These two methods are described below.

Creating a Dependency Association Between Existing Entities

You can create a dependency association between two entities that already exist in a model. 1 Select the entities that are to be associated. The first entity you select is the parent entity and the second entity you select is the dependent entity. 2 Click the Link button or choose InsertDependency Association. A line appears in the model connecting the two entities, and the Dependency Association dialog box opens:

3 Enter the Link Description, if you want one. 4 Click OK. On completion, the entities are linked by an arrow pointing towards the dependent entity.

2-17

Analysis StageBuilding a Concept Model Defining a Dependency Association between Entities

Inserting an Entity with a Parent

You insert an entity with a parent the same way you insert a weak entity, except that for an entity with a parent, the cardinality is always many. 1 Select the parent entity. If you are inserting an entity that already exists, it can only be inserted under the same existing parent concept. 2 Click the Entity button or choose InsertEntity. The mouse pointer changes to . Click the position in the model where you want to place the dependent entity. If, at this point, you change your mind and decide not to insert the entity, press <Esc> or click the Abort button to get out of concept insert mode. 3 A rectangle representing the entity appears in the model and the Entity dialog box opens, with a section at the bottom for information about the parent:

4 Choose New or Include. This switch indicates whether you are creating a new concept, or including a concept that already exists. 5 Enter the Entity Name. 6 Enter a Link Description if you wish. 7 Click OK.

2-18

Analysis StageBuilding a Concept Model Extending the Concept Definition

On completion, the entity name appears on the rectangle in the model. The arrow linking the two entities points towards the dependent entity.

2.7

Extending the Concept Definition

To extend the concept definition you have to access the Concept form.

To access the Concept form: Or Select a concept, and click the Fields button or choose ObjectFields. The Concept form is displayed:

1 Double-click a concept.

2-19

Analysis StageBuilding a Concept Model Extending the Concept Definition

First Groupbox

The first groupbox is used to identify the concept and supply additional information on the concept: NoAutoRulesets Rulesets and rules ensuring referential integrity are not automatically generated for the concept, and you are responsible for creating any necessary rulesets to ensure referential integrity. If you specify DB2 or SQL as the DBMS, this option is automatically assigned when you are defining fields for an association. For more information, refer to Part C Logic. External Lexicon The eMerge Lexicon is not used; i.e. an external lexicon is used. This option is useful when the database being used for a concept is not a eMerge DB1 database (e.g. in DB2 an index table is used in place of the Lexicon). Every field assigned the Name option is derived to the corresponding class (which is assigned the ShowKey option instead of the Name option). All the functionality of the eMerge Lexicon is via the index table, etc.

2-20

Analysis StageBuilding a Concept Model Extending the Concept Definition

However, if the Name option is assigned to the field directly in the class, the eMerge Lexicon is used. There is then a need for the two-phase commit mechanism. For a field mapped to SQL and assigned the Name option, the Lexicon Generation utility can be run on the data in the SQL table to create the eMerge Lexicon, after assigning the CreateLexicon option to the datasource of the database. DBMS Override the DBMS adapter used for the concept. See DBMS Adapter Guide. Forms Template Change the template assigned in the Forms Template field to override the template assigned to a particular concept in a model (as opposed to the template applied to the model). See "Form Templates" on page 43-1. Select a template to be used for the model in the Form Templates for forms created from this concept (both default forms and user-defined forms). Fields Groupbox The Fields groupbox is used to define the concept fields. It allows you to enter, view or change the fields describing the concept. See "Analysis StageDefining Fields and Domains" on page 3-1.

2-21

Analysis StageBuilding a Concept Model Extending the Concept Definition

2-22

Chapter 3 Analysis StageDefining Fields and Domains

3.1

Types of Concept Fields

A concept is described by its fields. There are three types of fields:

Key Fields
Key fields uniquely identify an occurrence of a concept. Each concept has a field (or a set of contiguous fields) to identify each concept occurrence. This expedites the search and the processing of the selected occurrence.

If you cannot establish an obvious unique key field for the concept, use some other ID like number field either random or sequential as the key field to help keep an occurrence of the concept unique.

At least one field must be designated as a key field. The key field is usually a numeric field. Example: The employees ID number. The key field for an entity is the subject field for the entity when this field appears in other concepts. The field is the target for referential integrity constraints in other concepts.

Name Field
Key fields are used as the primary index. In addition, you can define a name field as a secondary index for applications that store data in a DB1 (eMerge datasource). The name field is a character field (e.g. employee name) that is often unique, but does not have to be. The name field must be defined subsequent to the key field. The name field can be created from one or more fields. They are concatenated together to form one name field. Whenever a new occurrence of a class (with a name field defined) is added to the database, the system adds it to a "look-up table" of name fields

3-1

Analysis StageDefining Fields and Domains Data Type for a Field

against key fields, known in eMerge as the Lexicon. The Lexicon is used to access composite occurrences by their names instead of by their keys. The Lexicon creates a connection between each selected name and the associated composite number and key value. In this case, the lexicon serves as a secondary index. Example: For the Employee concept, the name field is made up of Family Name and First Name. Employee
Employee Family First Name Name ID Dept. No.

Attribute Fields
These supply additional details about the concept and describe the information which the organization manages about the concept. Example: An employee concept might include information about the date on which the employee was hired.

Temporary Fields
Temporary fields are used for calculations and data manipulations in business rules and presentation operations. They are defined via a concept as concept fields. They are not stored in the class which is the implemented concept. For Business Rules For Operations The NotInClass and NotInOperation options are assigned to the field. See "Temporary Fields" on page 12-6. The NotInClass option is assigned to the field. See "Including a Field in an Operation Not in a Concept" on page 33-11.

3.2

Data Type for a Field

Numeric
Numeric, Binary, PackedDecimal and ZonedDecimal. Positive numbers, zero, including decimal points.

3-2

Analysis StageDefining Fields and Domains Data Type for a Field

Numeric Fields

NotZero values)

A value of Zero is not allowed (the default is zero and positive Negative values are allowed.

MayBeNegative

Character
(Character, Fixed and Variable) The value specified for the Field Size of a concept character field (specified via the Concept form) determines the internal representation of the character field; fixed or variable:

A Field Size less than 17 results in a fixed length character field. A Field Size greater than 16 results in a variable length character field. A Field Size greater than 78 results in a long variable length character field (maximum size is 32000). If a value is not specified for Field Size, the default is variable length (less than 79 characters).

The following applies to long variable character fields (size from 79 to 32000): In a query output form, the maximum field size for a long variable character field is 255. Decoding/Encoding is not allowed Possible values cannot be specified. A default value cannot be specified: in the field definition for a field in an operation. The following options cannot be assigned: Name AlphaNumeric Description TechnicalDescription

For a field in an operation the following options cannot be assigned: VerificationField VerifySubject DefaultSubject For a field in a class the following options cannot be assigned: VerificationField

3-3

Analysis StageDefining Fields and Domains Data Type for a Field

Name

For a field in a block the following options cannot be assigned: Store Restore StoreUp RestoreFromUpper RestoreFromDown EchoedByRule The MultiLineEdit option can be assigned to a field having long variable character data type (size from 79 to 32000) via the GUI tab of the Field Definition form to enable presentation with wrapping and scrolling. MultiLineEdit cannot be overwritten on the field in form level. The information from a long character field is not stored in the global context or the user context. If needed, see your administrator to enlarge the task memory when working with long character fields.

All characters (letters, digits, blanks and special characters). Character Fields AlphaNumeric AlphaBetic Mixed Letters, blanks, numbers, " . - _ #

Letters, blanks, " . - _

Both upper and lower case characters are allowed.

SecondLanguage and SCL-Mixed Relate to second language fields. See Chapter 62, Applications with More than One Language.

Date
Must be a valid date. Change these default values by assigning options or defining a domain of possible values. Defining Date Fields Define a date field by specifying a value of Date in the Data Type field. The date format can be year, month-year or day-month-year. It is determined by the value in the Size field as shown in the following table: Size Field 2 4 yy yyyy European Format yy yyyy American Format

3-4

Analysis StageDefining Fields and Domains Defining Fields for a Concept

Size Field 5a 6 7 8 9 10 11
a

European Format mm.yy mon yy mm.yyyy dd.mm.yy dd mon yy dd.mm.yyyy dd mon yyyy

American Format mm.yy mon yy mm.yyyy mm.dd.yy mon dd yy mm.dd.yyyy mon dd yyyy

a a

Cannot be used in computations.

yy is a two-digit year and yyyy is a four-digit year. mm is the month represented by a number while mon is the month represented by a three letter month code. dd is the day. The default separator for date formats that include mm is . (i.e. a period). The default separator for date formats that include mon is a blank. The minimum value for the year in a date field is 1900. The maximum is 2898. The default Size for a date field is 10 (i.e. the default format is a daymonth-year).

Use the DATESEP command to change the default separators. See General Reference.

The Administrator can change the default date format from the European convention (day-month-year) to the American convention (month-day-year) or to a reversed format (year-month-day). See the Business Integrity Server Administration Reference. Date Fields ChangeDate Current date is inserted when the concept occurrence is changed only if the field is empty. CreateDate Current date is inserted when the concept occurrence is created only if the field is empty.

3.3

Defining Fields for a Concept

1 Double-click a concept. Or

3-5

Analysis StageDefining Fields and Domains Defining Fields for a Concept

Select a concept, and click the Fields button or choose ObjectFields. The Concept form is displayed:

2 Enter the fields needed for the concept in the Field Textbox:

The Key subgroupbox is used to define key fields (see "Key Fields" on page 3-1). The Name subgroupbox is used to define name fields (see "Name Field" on page 3-1). The Attr(s) subgroupbox is used to define fields that supply additional details about the concept (see "Attribute Fields" on page 3-2).

3 Enter the name of the field in the Field textbox. 4 Enter a Data Type and Size (and Decimal Places if needed). 5 If based on a domain, choose a domain in the Domain field.

3-6

Analysis StageDefining Fields and Domains Domain Concept

6 Assign any options required. For a full description of all the options effecting the field definition refer to the Form Reference.

3.4

Domain Concept
The domain concept describes a field of one or more other concepts. When you associate a field with a domain, the field inherits the characteristics of the domain: Data Type, Size etc. When you change the characteristics of a domain, the characteristics of all fields associated with that domain are changed accordingly. The domain concept does not have a graphic representation in the model. The domain is implemented as a field.

Uses for Domains

You can define a domain for the following purposes: Generic Field Definitions To create a generic field definition that can be applied to several fields in several concepts or for one field that is of interest to more than one concept. Example: Any field, which contains prices or wages, can have the same definitiona numeric field with two decimal places. Instead of specifying these details for each such field, you can create a domain with this definition, and attach it to all relevant fields. Possible Values To define either distinct values or a range of values or a combination of distinct values and ranges to be applied to a field in a concept. If a domain needs to have a specific list of possible input values which do not change often, add the list to the domain definition. Once added, any online input to fields using this domain is verified against the list. The domain of this type usually contains a small number of distinct values. Example: There are three divisions in the organization manufacturing, engineering, and sales. When data is entered into the DIVISION CODE field, or any other field used to indicate the division, you want to allow only M, E or S. You define these possible values as a domain attached to the DIVISION CODE field, and any other fields with the same field definition, for which the same restriction applies. Join Existing Fields To join a field that already exists in the knowledgebase, but was not created via Modeler.

3-7

Analysis StageDefining Fields and Domains Defining a Domain

3.5

Defining a Domain
There are two ways to define a domain:

Via the concept model Via the Concept form

Defining a Domain Via the Concept Model

1 Choose InsertDomain. The New Domain form is displayed:

2 Type the name of the domain in the first textbox. 3 Specify the field definition for the domain. Any field to which you apply this domain will have this definition. To join a field that already exists in the knowledgebase but was not created via Modeler, choose the field from the Field No. field. You need not define the fields data type, size, etc.
3-8

Analysis StageDefining Fields and Domains Defining a Domain

4 Specify values and/or ranges of values that describe valid data for the fields to which this domain applies.

For a distinct value: Enter a value in the Low Value field to specify the lower limit for a range, one value per occurrence. For a range of values: Enter values by specifying the lower end of the range in the Low Value field and the upper end of the range in the High Value field.

Values may be alphabetical or numeric, depending on the data type of the field. The validity of field values is checked prior to processing rules. Therefore, a rule can cause an invalid value to be accepted, after the default checking by the BLP. For example, negative values can be defined to a field via eMerge rules, but not entered directly. If your application includes rules that can define values which are not possible, you must use rules to check these values. You cannot have different sets of possible values for the same field in different forms. 5 Click in the Low Value or High Value field. Use the Value Meaning property field (Description category) to describe a value or a range. For a distinct possible value, the meaning of this value is displayed on the form. For a range of possible values, only the Low Value and High Value field values are displayed on the form. You must enter a value in the Value Meaning field. Value Meaning is a multilingual language field. If you are working in dual language mode or multilingual mode, the first character of the field value must be the Language short code. The short code is not actually displayed in any field in a form using the domain. For example, the E character identifies the language of the meanings as English. 6 Use the Explanation field for further explanation about a value for documentation purposes. 7 Click the OK button.

Defining a Domain via the Concept Form

1 Double-click a concept. The Concept form is displayed. 2 Enter a new domain name in the Domain field while you are defining a field. The domain is created automatically. This domain has the same

3-9

Analysis StageDefining Fields and Domains Defining a Domain

definition as the field for which it was created (the same Data Type, Size etc.). If you want the domain name to be the same as the field for which it is being defined, place an equal sign (=) in the Domain field. The name is copied automatically. 3 Click the Domain button. The Domain Definition form is displayed:

The form is used to define meanings and possible values for a domain. You cannot change the name of the domain in the Domain Definition form. The name can be changed only in the Domain field in the Concept form. 4 Specify the field definition for the domain. Any field to which you apply this domain will have this definition. To join a field that already exists in the knowledgebase but was not created via Modeler, choose the field from the Field No. field. You need not define the fields data type, size, etc

3-10

Analysis StageDefining Fields and Domains Defining a Domain

5 Specify values and/or ranges of values that describe valid data for the fields to which this domain applies.

For a distinct value: Enter a value in the Low Value field to specify the lower limit for a range, one value per occurrence. For a range of values: Enter values by specifying the lower end of the range in the Low Value field and the upper end of the range in the High Value field.

Values may be alphabetical or numeric, depending on the data type of the field.

You can override the possible values defined for a field based on a domain by using business rules (see Part C Logic).

You cannot have different sets of possible values for the same field in different forms. 6 Click in the Low Value or High Value field. Use the Value Meaning field to describe a value or a range. For a distinct possible value, the meaning of this value is displayed on the form. For a range of possible values, only the Low Value and High Value field values are displayed on the form. You must enter a value in the Meaning field. Value Meaning is a multilingual language field. If you are working in dual language mode or multilingual mode, the first character of the field value must be the Language short code. The short code is not actually displayed in any field in a form using the domain. For example, the E character identifies the language of the meanings as English. 7 Use the Explanation field for further explanation about a value for documentation purposes. 8 Click OK to save the data.

Reviewing and Modifying Existing Domains

You can review or modify all the domains defined for the enterprise model (i.e. all the domains defined in the knowledgebase). 1 Open an existing model.

3-11

Analysis StageDefining Fields and Domains Advancing a Concept to Design or Implementation

2 Choose Object > All Domains. The All Domains form is displayed:

3 Choose a domain and click the Definition button. The Domain Definition form for the selected domain is displayed.

Removing a Domain for a Particular Field within a Concept

1 Select the concept and click the Fields button. The Concept form for the particular concept is displayed. 2 Enter an asterisk (*) in the Domain field for the field for which you want to remove its domain. The domain is removed from the field. If the domain is not being used by other fields, not only is the domain removed from the field, it is also deleted entirely from the knowledgebase.

3.6

Advancing a Concept to Design or Implementation

This section gives a brief description of the stages that come after analysis: the design stage and the implementation stage. It provides a checklist of requirements that must be met before you can advance a

3-12

Analysis StageDefining Fields and Domains Advancing a Concept to Design or Implementation

concept to either design or implementation. It explains how to change the development stage of a concept. When you advance a concept to the design stage, Modeler automatically generates one or two designs, depending on how you defined the concept during analysisthe type of concept, its link with its parents, and its fields. You can modify the automatic designs or create new ones. If you want to accept the automatic designs, you can advance concept directly from analysis to implementation. When you advance a concept to the implementation stage, data structures and forms necessary to support the concept are generated and stored in the knowledgebase.

Requirements for Advancing

Modeler does not allow you to advance a concept to a higher stage unless you have performed all the activities necessary for the current stage. You can advance the concept from analysis to a higher stage only if the following requirements are met:

The concept cannot be at a higher development stage than that of its parents. Some types of concepts have to have fields in order to advance to a higher stage To Advance the concept

Concept Type Entity Weak entity cardinality = 1

To Design Needs at least one field. It need not be a key field. Needs at least one field. It need not be a key field.

To Implementation Needs at least a key field. Needs at least one field. It need not be a key field. Needs at least a key field.

Weak entity Needs at least one field. It need cardinality = Many not be a key field. Document

If you have not defined fields for a document, default fields are created automatically by Modeler when you advance the documents stage to design or implementation. Does not need fields. Does not need fields.

Association

3-13

Analysis StageDefining Fields and Domains Retreating to Analysis

You do not have to advance the stage of a domain. The stage of a domain is determined by the highest stage of a concept containing a field associated with the domain.

Changing the Stage of a Concept

1 Select the concept. On the toolbar, the stage button representing the current status of the concept is dimmed. 2 Click the A, D, or I button, or choose ObjectAnalysis, ObjectDesign or ObjectImplementation The color of the graphic symbol for the concept changes to the color indicating the new stage. Modeler sends the request to Business Integrity Server, and the appropriate modifications are made to the knowledgebase.

3.7

Retreating to Analysis
Even though Modeler prevents you from advancing to the next stage too soon, it is flexible in allowing you to make changes while the concept is in the design or implementation stage. Even after a concept has advanced to design or implementation, you can add fields and rules, and you can change the concepts link with its parents. These changes are reflected in the implementation. There are two very basic changes, however, that can be made only in the analysis stage:

changing the type of a concept (by using EditChange Type) changing the parent of a concept (by using EditReattach)

A concept can never be at a lower development stage than that of its dependents. If you decide to retreat to analysis, the concepts designs and physical structures (i.e. the classes within a composite created for the concept) are automatically deleted, but the field definitions are not deleted. Thus, when you again advance the concept to implementation, it may not create a class in a composite with the earlier number, even though the field numbers are still based on the earlier number. If you want field numbers to be in sync with the class in a composite number, for a concept that has been retreated from implementation, delete the fields after retreating the concept (via ObjectDelete Fields). Deleting the fields from the knowledgebase deletes the field definitions
3-14

Analysis StageDefining Fields and Domains Retreating to Analysis

attached to the concept. Thus, when the concept is advanced to implementation, the concept number and field numbers are in sync.

3-15

Analysis StageDefining Fields and Domains Retreating to Analysis

3-16

Chapter 4 Design Stage of a Concept

As you work in Modeler, each concept is in a clearly defined development stage. This chapter describes the design stagethe second of the three Modeler development stages: analysis, design or implementation. When a concept is in the design stage, its graphic symbol in the model is yellow. There are default designs generated automatically by Modeler. If you want to accept the default designs, and not create any new designs, you can change the status of the concept directly from analysis to implementation. Modeler then creates the default designs and implements them immediately.

4.1

Design Stage
When a concept is advanced to the design stage, a Main design is automatically generated for the concept. For an association, an OppositeToMain design is also generated. The Main and the OppositeToMain are the default designs. Additional designs can be created by the user. A design can be either physical or operation. For a physical design, Modeler creates physical structures (i.e. classes) and operations when the design is implemented. For an operation design, Modeler creates only an operation when the design is implemented.

Design stage button

4.2

Main Designs and Opposite-To-Main Designs

Main Design
Only one design can be the Main design for a concept. The Main design always has classes created for it when it is implemented. It can be modified as needed (see Modifying the Main Design on page 4-11).
4-1

Design Stage of a Concept Main Designs and Opposite-To-Main Designs

The Main option indicates that a design is the Main design. It cannot be unassigned. The Dynamic option is automatically assigned to the Main design and cannot be unassigned. This causes any fields added to the concept to be added automatically to the design.

Opposite To Main Design

When an association advances to the design stage, two default designs are automatically created for it. One is designated Main, and the other is designated OppositeToMain. The Main design has the non-main parent under the main parent, and the OppositeToMain design has the main parent under the non-main parent. The main parent is listed first in the Concept textbox. The default name of the OppositeToMain design is the name of the association with the digit 1 or 2 appended. The digit depends on which parent was selected first when the association was created.

When an association is implemented, the OppositeToMain design is not implemented unless you assign Implementation to the design. If you want the OppositeToMain parent order to be the Main parent order for an association, you must retreat to the analysis stage and designate the non-main parent as the main parent for the association.

Opposite To Main Design as an Index to an SQL Table

When an association between concepts with an SQL DBMS is implemented, the default OppositeToMain design is automatically defined as an SQL Index for Constructor of the Main design. You can assign the SQL-Index option in the Concept: New Design form to cause the design to be implemented as an SQL index for the design in the

4-2

Design Stage of a Concept Default Designs and User Designs

Referred Design field. You cannot assign or unassign the SQL-Index option to an existing design. See "SQL-Index Option" on page 4-6.

4.3

Default Designs and User Designs

You can review the default designs that result from the analysis. If the default designs do not meet all the needs of your application, you can modify them or define new ones to create additional database structures or to present additional views of the concept. You can implement more than one design for each concept. Default designs are either the Main design (generated for every concept) or the OppositeToMain design (generated for an association). User designs are the additional designs created by the user. User defined designs can be physical designs or operation designs.

4.4

Physical Designs and Operation Designs

On implementation, the Main and OppositeToMain designs generate physical structures and an operation. A user design, when implemented, generates either physical structures or an operation depending on whether the Physical or OperationOnly option is assigned.

4-3

Design Stage of a Concept Options

Physical Designs
The various parameters you select for the physical design determine, when the design is implemented, whether a class is created for the design, or whether the concepts fields are added to an existing class. The default designs are based on the concept type, cardinality, probability and fields you defined for the concept during analysis: type of concept One design is automatically generated for all concept types, except an association. In the case of an association, Modeler automatically generates two designs, which reflect the two sides of the association. The default name of the design is the name of the concept. the cardinality and probability The cardinality and probability you have defined (as applicable) for its link with its parents. For a nondependent entity, this is not relevant. For a document or an entity with a parent, the default cardinality of Many is used. fields the fields you have defined for the concept and for its parents

"Illustrations of Default Designs" on page 4-16, shows the structures generated in the database at implementation for these automatic designs.

Operation Designs
For information on operation designs see Chapter 33, Operations and Operation Methods.

4.5

Options
AutoRuleset Option
When the AutoRuleset option (Advanced category) is assigned, rulesets are automatically generated for the design to ensure referential integrity. AutoRuleset is assigned by default to the Main and OppositeToMain design if you are working with a native eMerge database. If you have specified DB2 or SQL/DS as the DBMS for the model, AutoRuleset is not assigned to the concept.

4-4

Design Stage of a Concept Options

GUI Option
When the GUI option (Advanced category) is assigned, the default forms generated for an implemented design have GUI definitions. GUI is assigned by default to every design.

Dynamic Option
The Dynamic option controls what happens to an existing design when you add fields to the concept.

When Dynamic is assigned to a design, any fields you add to the concept are added automatically to the design. When Dynamic is not assigned to a design, and you add fields to the concept, you must explicitly add the fields to the design, if you want them to appear in this design.

The Main design must have the Dynamic option (Advanced category) assigned. For a design which has been assigned IdentifierOnly, Dynamic has no effect.

IdentifierOnly Option
Assigning the IdentifierOnly option (Advanced category) defines a design that contains only the Key and Name fields. After the design is created, any other fields that you may need can be added. By default, the IdentifierOnly option is not assigned and all the fields defined for the concept are included in the design.

Implementation Option
Assigning the Implementation option (General category) indicates that the design is implemented when the concept is implemented. Implementation is not assigned by defaultto give you a chance to create the design the way you want before implementing it. Several designs can be implemented for a particular concept. The following points should be noted:

If you wish to build a design but not implement it at this point, do not assign Implementation.

4-5

Design Stage of a Concept Options

If you are defining a design for a concept that is not yet implemented, and you assign Implementation, the design is implemented only when the concept advances to the implementation stage. If you are defining a design for a concept that is already implemented, the design is implemented only after you explicitly assign the Implementation option.

If you have an implemented design, and you unassign Implementation, the data structures generated for the design are removed from the knowledgebase.

SQL-Index Option
When there is an association between concepts that are mapped to an SQL DBMS, and this association is implemented, the default OppositeToMain design is automatically defined as an SQL index for the Main design. A referred physical design with DB2/SQL is required for the SQL-Index design. By default, the main design is taken. The Referred Design of the SQL-Index cannot have a Link=Joined or OnlyOne. An SQL-Index design may be copied from another SQL-Index design and will have the same Referred Design as the original design. The SQL-Index design initially has all Referred Design fields. Some of them may be deleted later, and others may be added later. The non-key fields of the Referred Design may be defined as keys in the SQL-Index design and the keys of the Referred Design may be defined as non-key fields or may be completely deleted from the SQL-Index. Path fields of the Referred Design may be deleted or their order changed only if the SQL-Index design is implemented as a root class. The Physical option will be assigned automatically to the SQL-Index design. Once the SQL-Index design is defined, it cannot be changed to an OperationOnly design or to a regular Physical design. The AutoRuleset option or Banner use cannot be assigned to an SQL-Index design. For each type of concept (entity, weak entity and association) the parent concept's design number in the Order groupbox of an SQL-Index design is taken from the Referred Design and it will be allowed to change it only in the first Order.

4-6

Design Stage of a Concept Which Fields are Used

The SQL-Index design is defined as a dependent design of its Referred Design. It cannot be defined as a Referred Design of any other design. It cannot be defined as the Parent design of any other design. In the Implementation stage of an SQL-Index design, it will be verified that the class that represents it, is in a different composite than the class of the Referred Design; if both classes are in the same composite, the Structure in the first Order should be changed to Concatenated. The SQL-Index design will be implemented as a constructor, which is the Index for Constructor of the Referred Design. If DB2/SQL is added to the parents of an existing DB2/SQL association with an OppositeToMain design, or to the model to which it belongs, the OppositeToMain design remains a Physical non-Index design. If DB2/SQL is removed from the parents of an association with Index design or from a Model, the Index design will be deleted.

4.6

Which Fields are Used

By default, when a design is created, all the fields in the concept and the parent concept are included. Any fields that are not needed can be deleted after the design is created. The Fields groupbox allows you to delete fields from a design and to add or delete non-key fields of the concept and of its parent concepts. When the IdentifierOnly option (Advanced category) is assigned, only the key and name fields are initially included in the design.

4.7

Link Between the Concept and its Parent

The Link describes the link between the concept and its parent. It is a combination of the cardinality and probability defined for the concept. When a dependent concept is implemented, depending on the value of the Link parameter:

The fields of a dependent concept are placed in the class of the parent concept. The dependent concept is placed in a separate class.

If Link causes the dependent concept to be placed in a class of its own, by default its class is dependent to the parent class.

4-7

Design Stage of a Concept Link Between the Concept and its Parent

Changing the Structure

You can use the Structure field to force the dependent concepts class to be at the same level as the parent class. See "Structure" on page 4-9.

Default Links
If you do not specify a value for Link, Modeler chooses the link based on the cardinality (many or one) and the probability (mandatory, high, or low) you have defined for the concept, as shown below: Cardinality many one one one Probability Mandatory High or Low Mandatory High Low Many Joined Only One OneToOne Link

Implemented Structure for Links

The following table shows the links and a diagram of the implemented structure (in the diagrams, A represents the current concept and B represents the parent concept): Link Many Explanation There can be multiple occurrences of the dependent concept. The fields of the dependent concept are always be placed in a separate class. By default, this is a dependent class. If you specify Structure value of Concatenated this is a separate class at the level of the parent class. See the discussion on the Structure field on page 4-9.

B A1
Joined

A2

A3
There can be only one occurrence of the dependent. It always appears. By default its fields are placed in the parent class. The key field must be supplied when a new occurrence of the concept is inserted (MustInsert has been assigned). There is no separate class created for the dependent concept. Instead, the fields are joined to the parent concept.

4-8

Design Stage of a Concept Changing the Parent Design Used by a Dependent Concept

Link OnlyOne

Explanation There can be only one occurrence of the dependent concept. It is very likely to appear. By default its fields are placed in the parent class. A separate operation and class are generated for the dependent concept. There can be only one occurrence of the dependent. It is not very likely to appear. By default its fields are placed in a dependent class, assigned the OneToOne class in composite option.

B
OneToOne

Changing the Link

You can change the link, if the default link for the cardinality and probability assigned in analysis is not appropriate to a particular design, based on the following:

When the cardinality is Many, the link can only be Many. When the cardinality is One, you can assign any of the links OneToOne, OnlyOne, or Joined.

4.8

Changing the Parent Design Used by a Dependent Concept

By default, the main design of a parent concept is used as the design for the parent in any design for a dependent concept. However, if you do not wish to use the main design of the parent concept for a dependent concept, the design can be changed to another design.

4.9 Structure

To change the parent design used: Specify the appropriate design number of the parent concept in the Design field in the Order subgroupbox.

The Structure field is used for dependent concepts only. The Structure determines where the dependent concept fields are placed relative to the parent concept.

4-9

Design Stage of a Concept Structure

Dependent Structure
The fields of the dependent are placed in a dependent class of its own. For example:
Order Order-no = Key concept fields Line-no = Key concept fields

Order Line

If the Link is OneToOne or Many, the default structure is Dependent and a dependent class is created for the dependent concept on implementation. If the Link is Joined or OnlyOne, the structure is Dependent. However, it has no meaning, because for Link Joined or OnlyOne, the dependent concept is not implemented as a separate class. That is, the fields of the dependent are placed in the parent.

Concatenated Structure
The fields are placed in the class of the parent concept. For example:
Order Order-no = Key concept fields Order Order-line Order-no = Key Line-no = Key concept fields

In design, you can place Concatenated in the Structure, if you do not want the dependent concept to be placed in a dependent class on implementation. The dependent concept is then placed in a class on the same level as that of its parent. If the parent is a root class, the dependent becomes a root class. If the parent is not a root class, the dependent appears directly under its grandparent. The key of the parent becomes part of the key of the dependent, as shown in the chart below, instead of being a path key for the dependent class.

Changing the Structure

Specify the appropriate structure in the Structure field. In some cases, the structure of a concept cannot be changed when the concept is in the implementation stage. Changing the Structure when the
4-10

Design Stage of a Concept Modifying the Main Design

concept is in the implementation stage (e.g. changing to Concatenated from Dependent) creates a class for the dependent concept on the same level as that of its parent. However, the field numbers that existed before the change remain in effect (since they were already implemented in the knowledgebase). See "Illustrations of Default Designs" on page 4-16 for examples of the various structures of dependent concepts with Link of OneToOne or Many.

4.10 Modifying the Main Design

The definition of the Main design, that is automatically defined for a concept, can be viewed and modified. 1 Right-click the concept and choose ObjectConcept Design, the Concept: Design (2013) form is displayed:

2 Make any modifications you need and click Apply.

4-11

Design Stage of a Concept Creating a New Design

4.11 Creating a New Design

The concept must be in the design stage or the implementation stage in order to be able to create any new designs for it. To change the status of a concept, See "Changing the Status of a Concept" on page 4-28. 1 Right-click the required concept (in design or implementation stage) and choose ObjectConcept Design. The Concept: Design (2013) form opens, displaying the main design for the concept. 2 Click the NewDesign button. The Concept: New Design (2009) form is displayed:

3 Enter the design number and name. The design number can be a number from 2 to 999. If you do not specify a design number, Business Integrity Server automatically specifies a number by adding one to the last existing design number. 4 Assign the Physical option to the design.
4-12

Design Stage of a Concept Modifying an Existing Design

5 Assign any other options needed. 6 Click Apply. The design is created according to the definitions.

The design can be implemented later, by using the Implementation option. See "Implementation Option" on page 4-5.

4.12 Modifying an Existing Design

You can view and modify the definition of any existing design. The designs are either default ones that were created by the system or designs inserted by the user.

To modify an existing design:

1 Right-click the concept (in design or implementation stage) and choose ObjectConcept Design. The Concept: Design (2013) form opens, displaying the main design for the concept. 2 Right-click the design field and choose All Concept Designs from the popup menu. The Concept: All Designs (2043) form is displayed:

4-13

Design Stage of a Concept Design Examples

3 Select the required design and right-click in the design textbox selected. Select Detail form the pop-up menu that is displayed. The Concept: Design Definition (2027) form is displayed:

4 Make any modification you need and click Apply.

4.13 Design Examples

Designs can be illustrated by a model of a personnel department. Among the services that the department performs for the organization are the following: Payroll Office Carpool Desk Calculates the employees salary and benefits. Organizes ride sharing.

Each of these functions involves the Employee entity shown in this concept model:

During analysis, the Employee entity and the Child weak entity were defined with several fields. When the concepts were advanced to the design stage, the following designs were generated:

4-14

Design Stage of a Concept Design Examples

However, Payroll Office and Carpool Desk need only a subset of the fields of the concepts. Therefore, new designs can be created if needed.

Payroll Office
Payroll needs salary information, including information about the employees familye.g. tax credits for children, whether spouse works, etc. Because the payroll calculations are done on a routine basis, and involve large amounts of data (e.g. the number of hours the employee worked each day) for performance and resource considerations a separate physical design can be created to contain only the information needed for payroll calculations (i.e. not all the fields are needed).

Carpool Desk
Carpool needs the name, address and phone number, but does not need information about the employees family.

4-15

Design Stage of a Concept Illustrations of Default Designs

Because this office needs a simple subset of the fields defined for the Employee entity, it is not necessary to create a new design.

4.14 Illustrations of Default Designs

The charts in this section show the structures generated in the database at implementation by the default designs created automatically by Modeler for the various types of concept. For convenience, each concept illustrated in the chart has been given a name which is the same as its type. Fields of a concept have been named Field or Key Field, prefixed by the initials of the concept. For example, the key field for the weak entity is WE Key Field. Every default design is a main and a physical design, and has AutoRuleset, GUI and Dynamic options assigned, except the following:

A document is not assigned AutoRuleset. For an association, the design for the non-main side has been assigned OppositeToMain instead of Main.

Entity
Link Composite structure Class structure

The key field for an entity is the subject field for the entity when this field appears in other concepts. The field is the target for referential integrity constraints in other concepts. The Entity option is mainly needed in cases where the field appears in other concepts which are not dependent on the current concept, in order to support relationships between the current concept and the other concepts. Assigning Entity results in the following: The client select form in the subject definition is automatically set to the multiple occurrence form generated automatically for the concept. This means that whenever the Select button is clicked, with the cursor positioned in this key field in any other form, the select form is then displayed. The client detail form in the subject definition is automatically set to the single occurrence form generated automatically for the concept.
4-16

Design Stage of a Concept Illustrations of Default Designs

This means that whenever the Zoom button is clicked, with the cursor positioned in this key field in any other form, the client detail form is then displayed.

Entity in a Dependency Association with Another Entity

Link Default Link = Many, Entity is the parent of Entity 2 Composite structure Class structure

Weak Entity
See the description of the Link field for an explanation of the difference between Link = Many, Link = Joined, Link = OnlyOne, and Link = OneToOne. Link Link = Many Default: Structure=Dependent Link = Many Structure=Concatenated Composite structure Class structure

Link = Joined or OnlyOne

4-17

Design Stage of a Concept Illustrations of Default Designs

Link Link = OneToOne Default: Structure=Concatenated Link = OneToOne Structure=Concatenated

Composite structure

Class structure

Link = OneToOne

Document
Link Default Link = Many Composite structure Class structure

4-18

Design Stage of a Concept Illustrations of Default Designs

Entity with a Child and a Grandchild with Link=Many

Structure Defaults: Weak entity design: Structure with entity=Dependent Document design: Structure with weak entity=Dependent Weak entity design: Structure with entity=Dependent Document design: Structure with weak entity=Concatenated Composite Structure Class Structure

4-19

Design Stage of a Concept Illustrations of Default Designs

Structure Weak entity design: Structure with entity=Concatenated Document design: Structure with weak entity=Concatenated

Composite Structure

Class Structure

Weak entity design: Structure with entity=Concatenated Document design: Structure with weak entity=Dependent

Association
In the following association between Entity 1 and Entity 2, Entity 1 is the main parent. A recursive association (i.e. between Entity 1 and itself) is illustrated on "Recursive Association" on page 4-23. For all types of links shown in the chart, the first row of structures listed refer to the Main design, and the second row of structures listed refer to the OppositeToMain design. For a many-to-many association, the two designs reflect the two sides of the association in second normal form; the many-to-many association is normalized as two one-to-many associations. Note that for each side of an association, the Link in that direction determines whether a dependent class is or is not built. If one parent of an association has Link value of Joined, the fields of this parent appear among the fields of the other parent of the association. The key will be a foreign key, assigned MustInsert. If this parent has a name field, it is assigned VerifySubject and DefaultSubject. If both
4-20

Design Stage of a Concept Illustrations of Default Designs

parents have link value of Joined, the key and name of each are assigned MustInsert, VerifySubject and DefaultSubject among the fields of the other side of the association.

Link Main: Link=Many

In the chart below triggered rulesets are listed that were created automatically during implementation. The rulesets contain rules that are required to ensure referential integrity between different designs of the same concept.

Composite structure

Class structure

OppositeToMain: Link=Many

Main: Link=Joined

OppositeToMain: Link=Many

4-21

Design Stage of a Concept Illustrations of Default Designs

Link Main: Link=OnlyOne

Composite structure

Class structure

OppositeToMain: Link=OnlyOne

Main: Link=Joined

OppositeToMain: Link=OnlyOne or OneToOne

Association with a Key Field and a Field

The association between Entity 1 and Entity 2 has a key field and a field. Entity 1 is the main parent.

4-22

Design Stage of a Concept Illustrations of Default Designs

Link Main: Link=Many

Composite structure

Class structure

OppositeToMain: Link=Many

Recursive Association
In the following recursive association for Entity 1, the parent with prefix P1 is the main parent Link Main: Link=Many Composite structure Class structure

OppositeToMain: Link=Many

Recursive Association with a Key Field and a Field

In the following recursive association for Entity 1, the parent with prefix P1 is the main parent. The association has a key field and a field.

4-23

Design Stage of a Concept Automatic Fields and Shared Parents

Link Main: Link=Many

Composite structure

Class structure

OppositeToMain: Link=Many

4.15 Automatic Fields and Shared Parents

Because of special kinds of association definitions, there are cases where the same field must be joined more than once to a concept or to a concept design. Since a field cannot appear more than once in a design, an automatic field is created. An automatic domain, representing the original field, is created as well.

4-24

Design Stage of a Concept Automatic Fields and Shared Parents

Example: Two Associations with Link=Joined Between Two Concepts

If you must create two associations with Link=Joined between two concepts, the key field of the joined parent must be linked twice to the first parent.

In the above figure, the key of Country must be linked twice to Product.

Example: Association with the Same Concept as Both Parents

An association may have the same parent concept for both its parents.

4-25

Design Stage of a Concept Automatic Fields and Shared Parents

If the above concept model is created, the following default structure is created. (Only the key fields are shown.)

Item-no appears twice in Business Integrity Server records for Order and What Delivered. This means, for example, the delivered item can be different from the ordered item. The same key field Item-no has to be defined twice for the Main and OppositeToMain designs of the Delivered Ordered Item association. Since a field cannot appear more than once in a design, an automatic field and an automatic domain are created. The automatic domain has the same name as the original field. The automatic field is based on the original field via the automatic domain. Thus, the automatic field inherits all its definitions from the original field (data type, size, field options and decimal point). The name of the automatic field has a numeral n concatenated to the name of the original field. n is an integer (beginning with 1) incremented for each automatic field defined for a particular original field. You can change the name of an automatic field via the Concept: Auto Fields (2024) form. Duplicate key fields can be removed when shared parents are defined for an association. Define a shared parent for an association via ObjectShared Parent. This menu item accesses the Shared Parents (2003) form. Example: If the Delivered Ordered Item association is defined to have Item as a shared parent, then the following structure is created with

4-26

Design Stage of a Concept Advancing a Concept to Implementation

Item-no appearing only once in each composite. In this example, the delivered Item must correspond to the ordered Item.

4.16 Advancing a Concept to Implementation

When you advance a concept to the implementation stage, Modeler creates, in the knowledgebase, the physical data structures, operations, and default forms necessary to support the concept. Structures are created based on each design for which Implementation is assigned. See "Default Designs and User Designs" on page 4-3. This section provides a checklist of requirements that must be met before you can advance a concepts status to implementation. It explains how to change the development stage of a concept.

Implementation stage button

Requirements
Before you can advance the status of a concept from design to implementation, the following requirements must be met:

A concept can never be in a higher development stage than that of its parents. Some types of concept cannot advance to the implementation stage unless they have fields:

4-27

Design Stage of a Concept Retreating to Design

Concept type Entity Weak entity cardinality = 1

To advance the concept to implementation Needs at least a key field. Needs at least one field. It need not be a key field.

Weak entity Needs at least a key field. cardinality = Many Document If no fields were defined when the document was in analysis, default fields were created when the concepts status advanced to design. Does not need fields.

Association

Changing the Status of a Concept

1 Select the concept. On the Concept Model toolbar, the button representing the current status of the concept is dimmed. 2 Choose the A, D, or I button from the toolbar. The color of the graphic symbol for the concept changes to the color indicating the new stage. Modeler sends the request to Business Integrity Server and the appropriate modifications are made to the knowledgebase.

4.17 Retreating to Design

Modeler is flexible in allowing you to make most modifications to your concept even after it has advanced to the implementation stage. A concept can retreat to a lower development stage only if the concept is at a higher development stage than that of its parents. You must retreat to the design stage if you want to make hierarchical changes to the structure of a design (in the Concept: Design (2013) form) when it is in the design stage. When you retreat from implementation, the constructors and data structures are deleted, but not the fields and the rules you defined for concept. If you retreat from the implementation stage to make structural changes, the changes may result in a totally new constructor being created when

4-28

Design Stage of a Concept Retreating to Analysis

the revised design is implemented. In this case, you will want to delete all the field numbers not automatically erased during retreat, and thereby bring the concept to a reset status where nothing remains from the previous implementation. To do this, select the concept and choose ObjectDelete Fields.

4.18 Retreating to Analysis

In order to make the following structural changes, you must retreat to a lower stage:

You can only change a concepts parents (via EditReattach) when it is in the analysis stage. An exception to this is a dependency association between two entities. The dependency association can be changed even if the entities are in implementation. You can only change a concepts type (via ObjectChange Type) when it is in the analysis stage.

4-29

Design Stage of a Concept Retreating to Analysis

4-30

Chapter 5 Implementation Stage of a Concept

This chapter describes the implementation stagethe third of the three Modeler development stages: analysis, design and implementation. When a concept is in the implementation stage, its graphic symbol in the model is green.

5.1

Implementation Stage
When you advance the concept stage to implementation, Modeler creates, within the knowledgebase: The data structures necessary to support the concept (composite and class definitions etc.). The database structures are based on the designs that have been created for the concept during the design stage. See "Design Stage of a Concept" on page 4-1 for descriptions of the parameters you can control, so that the implementation is as you want it. Field numbers for each field. The field numbers can be viewed via the Concept form for the implemented concept. Data forms so that data can be entered, retrieved, changed or deleted. These forms can be accessed directly from Modeler when you test the application.

Implementation stage button

When a concept is in the design stage or the implementation stage, you cannot change its parents or its type. An exception to this is a dependency association between two entities. The dependency association can be changed, even if the entities are implemented. Other changes are supported, and cause the appropriate structural changes to be made in the knowledgebase.

5-1

Implementation Stage of a Concept Testing the Application

5.2

Testing the Application

When you advance the concept to implementation, Business Integrity Server creates a class in a composite for the concept, and automatically creates forms for it. You can use these forms as soon as they have been created (e.g. to demonstrate the application to the user representative and get user feedback). Test the form by entering data and checking any possible value restrictions defined by domains attached to the fields. You can follow the form flow to dependent concepts by using the form actions.

To test the design of a concept:

1 Select the concept in the concept model. It must be in the implementation stage. 2 Click the Test button or choose ObjectTest Application. Modeler opens the form that has been created for the concept.

3 When you are finished testing the form, click the Quit button or as indicated in the form.

5.3

Working with Implemented Concepts

After you have built a working concept model, where at least some of the concepts have been implemented, you can enhance the concept model based on the users comments, and refine it further according to specifications. You can always expand a working concept model by adding concepts. This section discusses modifications that can be made to a concept that has been advanced to the implementation stage. Enhancements to an implemented concept are made at two levels:

some enhancements can be made directly to the implemented concept some changes require retreat from implementation status to the design or analysis stage

Enhancing the Implemented Concept

Even when a concept is at the implementation stage, Modeler allows modifications to the definitions you made at lower developmental stages. The following are some of the modifications you can make to an implemented concept in a working concept model, without retreating to a lower stage. You thus preserve all definitions that you made. Only the
5-2

Implementation Stage of a Concept Defining Default Values for a Field

specific changes you make to a parameter are reflected in the constructor definition:

Adding, deleting or changing fields (in the concept itself, or in a design). Most changes to the structure: dependent or concatenate. Changing the probability or cardinality. Adding designs or changing existing designs. Changing the database interface.

Removing a Domain for a Particular Field within a Concept

1 Select the concept and click the Fields button. The Concept form for the particular concept is displayed. 2 Enter an asterisk (*) in the Domain field for the field for which you want to remove its domain. The domain is removed from the field. If the domain is not being used by other fields, not only is the domain removed from the field, it is also deleted entirely from the knowledgebase. If the removed domain and the field had the same name, note that the field number for the field is changed; i.e. a new field is created.

5.4

Defining Default Values for a Field

If no values were defined for a field, it is stored as a null value. A null value is translated, on output, to zero for a numeric field or to blanks for a character field. You can define a default value at the field, operation, or form level, and via rules. The defaults are applied according to the following order of precedence:

Data Rule Presentation Rule Form Definition Operation Definition Field Definition

5-3

Implementation Stage of a Concept Defining a Global Default Value

Defaults set by data rules or presentation rules can be conditional. There can be many different default values and default conditions. Data rules directly affect the database. Presentation rules and defaults set by the form and operation affect the input to the database.

5.5

Defining a Global Default Value

When a constructor is defined, all of the fields in the constructor are empty. You can define a default field value for a field, which is stored in each occurrence of the constructor in the database, unless overridden.

Defining the Global Default Value

1 Using Modeler, right-click the concept and choose Object > Concept Design. The Concept: Design (2013) form for the concept is displayed. 2 Select a concept field and right-click in the field. Select Detail from the pop-up menu that is displayed. The Field Definition (2108) form for the particular field is displayed:

3 Enter the default value, as a hexadecimal value, in the Default (in Hex) (Editing category) field.
5-4

Implementation Stage of a Concept Using Synonyms

Global Default Rules

The following rules apply for the different data types: Numeric, Binary, PackedDecimal, or ZonedDecimal Character The two bytes are considered as a hexadecimal number. For example, the decimal value '64' is specified as '0040'. The left byte is considered as a fill character to be repeated in every byte of the field. For example, the value 'AAAAA' for a field with length 5 is specified as 'C100'. The values '0000' and '4000' both yield blanks. To define a default value to a character field the character field must not be variable length. Date If the default is 'FFFF' the default value is the date 31.12.2899. For a field having the EndDate option, this value specifies that the period, whose end date is the field's value, has not ended and is still open. The default value for a date may be given by assigning the ChangeDate, CreateDate or ChangeEndDate options. A value of '0001' as the default for a date field specifies that if a month and a year are given for some input value and the day is omitted, a day of 01 for the date will be stored for the field. If the date field is defined to include only a month and a year, a default of '0001' specifies that if only a year is given for some input value (and the month is omitted), a month of 01 for the date will be stored for the field. A value of '0101' as the default for a date field stores the day and month 01.01 for an input value including only a year. If a date field with a default is used in a rule attached to an operation (and not to a class), the default value is not considered during execution of the rule. HexaDecimal The first byte is the default value for the first byte in the field value. The second byte is used as a fill character for the rest of the field value.

5.6

Using Synonyms
Data objects (fields, classes, composites, and operations) can be referenced by their name and/or their number. The name can be replaced by a synonym.

5-5

Implementation Stage of a Concept Using Synonyms

Automatically Defined Synonyms

A synonym is given automatically to an object upon object definition unless the NoAutoSynonyms option has been defined for the database. The automatically defined synonym consists of a letter (alpha character) specific to the object type, concatenated with the unique object number: F S R T field (For example: F3000) class (For example: S33) composite (For example: R33) operation (For example: T3000)

You can define your own synonyms for an object. You can keep the automatically defined synonym unique by not defining your synonyms or naming objects with the automatic synonym naming convention.

Define a Synonym for a Field

You can define a synonym for a field: 1 Using Modeler, right-click the concept and choose Object > Concept Design. The Concept: Design (2013) form for the concept is displayed.

5-6

Implementation Stage of a Concept Using Synonyms

2 Select a concept field and right-click in the field. Select Detail from the pop-up menu that is displayed. The Field Definition (2108) form for the particular field is displayed:

3 Select the Synonym tab. Enter any synonyms. The automatically defined synonym is the first synonym. 4 Click OK.

Defining Synonyms for a Class

You can define synonyms for a class: 1 Using Modeler, right-click the concept and choose Object > Concept Design. The Concept: Design (2013) form for the concept is displayed.

5-7

Implementation Stage of a Concept Using Synonyms

2 Right-click in the Design textbox and select Class from the pop-up menu that is displayed. The Constructor: Class Definitions (100217) form is displayed:

The automatically defined synonym is the first synonym. 3 Enter any synonyms for the class in the subsequent First andSecond textboxes (Synonyms category). 4 Click OK.

Defining Synonyms for a Composite

You can define synonyms for a composite: 1 Using Modeler, right-click the concept and choose Object > Concept Design. The Concept: Design (2013) form for the concept is displayed. 2 Right-click in the Design textbox and select Composite from the pop-up menu that is displayed. The Constructor: Composite Definitions (100301) form is displayed:

5-8

Implementation Stage of a Concept Listing Composite Structures

The automatically defined synonym is the first synonym. 3 Enter any synonyms for the composite in the First and Second textboxes. 4 Click OK. To define a synonym for an operation see "Using Synonyms" on page 33-21.

5.7

Listing Composite Structures

When you advance a concept to the implementation stage, Modeler builds structures for it in the database. You can display a diagram of the composites and classes that have been created. The fields of the class and rules are depicted as well.

Listing the Structure of the Main Design

You can list the structure of the main design of a concept: 1 Select the concept in the concept model. 2 Choose ObjectComposite Structure

Listing the Structure of a Specific Design

You can list the structure of a specific design of a concept from a concept model: 1 Select the concept in the concept model. 2 Choose ObjectConcept Design. The Concept: Design form is displayed. 3 Display the design of interest. See "Modifying an Existing Design" on page 4-13.

5-9

Implementation Stage of a Concept Listing Composite Structures

4 Right-click in the Design textbox and select Composite Structure from the pop-up menu that is displayed. The structure of the composite is displayed:
PAGE: 1 COMPOSITE: EMPLOYEE ( 30) ...... 0. CLASS: EMPLOYEE ( 30) ASCENDING OPER************++++++++++++++++++++++--------------------------------3000| EMPLOYEE | LAST | FIRST | BIRTH | START EM-| PASSPORT | 3003| ID | NAME | NAME | DATE | PLOYMENT | NO | 3004| ( 3001) | ( 3002) | ( 3003) | ( 3004) | ( 3005) | ( 3006) | | B/4 | C/15 | C/15 | T/4 | T/4 | C/12 | ************++++++++++++++++++++++-------------------------------------------------------------------------------------------------| SEX | ADDRESS | NUMBER | STREET | CITY | ZIPCODE | | | NO | | | | | | ( 3007) | ( 3014) | ( 3015) | ( 3016) | ( 3017) | ( 3018) | | C/1 | B/2 | C/4 | C/15 | C/15 | C/9 | -----------------------------------------------------------------PAGE: 2 -----------------------------------------------------------------| COUNTRY | CUSTOMER | CONTRACT | PROJECT | START | FUNCTION | | | ID | ID | ID | DATE | | | ( 3319) | ( 3101) | ( 3105) | ( 3109) | ( 3020) | ( 3021) | | C/15 | B/4 | C/9 | C/5 | T/4 | C/1 | -----------------------------------------------------------------......... 1. CLASS: REVIEW ( 3001) ASCENDING, MAY DELETE ALL BROTHERS OMITTING THE KEY, CLASS IS A DOCUMENT CLASS OPER************----------3001| SEQ NO. | REVIEW | | | TEXT | | ( 3008) | ( 3009) | | B/2 | C/VAR | ************----------PAGE: 3

......... 1. CLASS: SKILL ( 3002) ASCENDING OPER************--------------------------------3002| SKILL | FROM | TO YEAR | SKILL | | CODE | YEAR | | DESC | | ( 3010) | ( 3011) | ( 3012) | ( 3013) | | B/2 | T/2 | T/2 | C/VAR | ************---------------------------------

5-10

Implementation Stage of a Concept Automatic Rules

5.8

Automatic Rules
If you create more than one physical design for a concept, rulesets and rules are generated automatically to ensure referential integrity. Automatic rulesets and rules are created when:

A concept, which has two or more physical designs that have Implementation assigned, advances to the implementation stage. A physical design is added to an implemented concept and it has Implementation assigned.

The automatic rules are needed between designs, so that changes in the data of one implemented design are updated in the other implemented designs. For every implemented non-main design of an implemented concept, two automatic rules are defined:

From the main design to this design. From this design to the main design.

Example: On entering an Item under Inventory, in an association with the following structure, the Inventory constructor under Order is automatically updated with the relevant data, and vice-versa:

When you retreat a concept from the implementation stage, all automatic rules are deleted. When a physical design of an implemented concept has Implementation unassigned, the implemented structures, including the automatic rules, are deleted.

Controlling Automatic Rules On the Concept Level

To delete all the automatic rules for all designs of a particular concept, assign NoAutoRulesets (General category) on the Concept (2108) form. To restore all the automatic rules, make sure AutoRuleset (Advanced category) on the Concept Design (2013) form is not assigned. By default, AutoRuleset is not assigned.

5-11

Implementation Stage of a Concept Retreating to Design or Analysis

Controlling Automatic Rules On the On the Design Level

To delete all the automatic rules for a particular design, unassign AutoRuleset on the Concept Design (2013) form. If you are using an eMerge native database, AutoRuleset is assigned by default. If you specify DB2 as the database interface, AutoRuleset is not assigned to an association. If you add a rule to an automatic ruleset, the automatic ruleset is not treated as automatic (e.g. it is not deleted automatically when the concept is retreated from implementation). However, the automatic rules (attached to this ruleset) remain automatic. If you add text to an automatic rule, the rule and the ruleset to which it is attached cease to be treated as automatic. However, any other automatic rules that were attached to the ruleset continue to be treated as automatic.

5.9

Retreating to Design or Analysis

Though most changes can be made when the concept is in the implementation stage, the types of changes listed here require retreat to design or to analysis:

the type of the concept can only be changed when the concept is in the analysis stage the parents of the concept (except for entities) and, for an association, the designation of which parent concept is the main parent can only be changed when the concept is in the analysis stage some structural changes which may result in changes to the hierarchy are only possible at the design stage

A concept can never have dependents at a higher development stage than its own stage. When you retreat from implementation, the automatic rules created for the concept are deleted. They are generated again when you again advance to implementation. When you retreat from the design stage, the designs are deleted. It is possible to retreat directly from implementation to analysis.

5-12

Implementation Stage of a Concept Retreating to Design or Analysis

Deleting Fields
Usually when a concept is implemented, the field numbers created for the field definitions are based on the number defined for the concept. However, when you retreat from the implementation stage, Modeler automatically deletes the class within a composite created for the concept, but does not automatically delete the field definitions. Thus, when you again advance the concept to implementation, it may not create a class within a composite with the earlier number, even though the field numbers are still based on the earlier number. If you want field numbers to be in sync with the class within a composite number, for a concept that has been retreated from implementation, delete the fields after retreating the concept (via ObjectDelete Fields). Deleting the fields from the knowledgebase deletes the field definitions attached to the concept. Thus, when the concept is advanced to implementation, the concept number and field numbers are in sync.

5-13

Implementation Stage of a Concept Retreating to Design or Analysis

5-14

Chapter 6 Working with the Concept Model

Most of the operations described in this chapter are accessed from the Edit menu for a concept model.

6.1

Excluding a Concept
Excluding a concept removes the concept from the model, but does not remove it from the knowledgebase. You can bring the concept back into the model later on, or use it in other models.

To exclude the concept:

1 Select the concept that you want to exclude. 2 Choose EditExclude.

6.2

Deleting a Concept
Deleting a concept removes the concept from the concept model and from the knowledgebase. You can delete a concept only after it has been excluded from all other models in which it appears.

To delete a concept:
Use Object>Reports to produce a report listing all models that include the concept. See Chapter 8, Printing and Generating Reports.

1 Exclude the concept from all other models in which it appears.

2 Select the concept that you want to delete. 3 Choose EditDelete.

6.3

Deleting a Dependency Association

Deleting a dependency association removes the link between the two entities.

6-1

Working with the Concept Model Deleting a Model

To delete a dependency association:

1 Select the link between the two entities. 2 Choose EditDelete.

6.4

Deleting a Model
You can delete a model only after all concepts that are shared by more than one model (i.e. included concepts) were excluded from the model. See above for information about excluding concepts.

To delete a model:

1 Exclude all the concepts that are included in the model. 2 In the Data tab, expand the Models node and right-click the model you want to delete. A pop-up menu is displayed.

3 Choose Delete Model. The model is deleted.

6.5

Opening a Concept from the Navigation Pane

To open a particular concept from the tree in the navigation pane:

1 From the Data tab, right-click the Models node. 2 Choose Open Concept. The Open Concept form is displayed:

6-2

Working with the Concept Model Moving a Concept

3 Click on the down arrow displays a list of all the concepts in the Enterprise Model. Select the needed concept. Or Enter the name of the concept. A wildcard can be used.

6.6

Moving a Concept
You can rearrange the structure and positioning of a concept in the model by moving the concept. The change is only graphical and is used to clarify the model display. That is, the concept remains connected to the same concept it was connected to before the move. If the Change Port on Move option is assigned (via View > Options > Preferences > Defaults), Modeler changes the ports as necessary whenever you move a concept. This keeps the model neat, uncluttered and easy-to-understand because the links between concepts are kept as simple as possible. If the option is not assigned, the ports remain where they were before the move.

To move a concept in a concept model:

1 Select the concept that you want to move. You can move more than one concept at a time by holding down <Shift> and selecting the concepts you want to move.
Make sure that you are not dragging one of the selection indicators ( resize the concept instead of moving it. ), or you will

2 Drag the concept(s) to the new location.

6.7

Resizing a Concept
You can change the size of the symbol for a concept within a concept model. Resizing a concept is not the same as using the zooming commands on a model.
6-3

Working with the Concept Model Changing the Parent of a Concept

To resize a concept:

1 Select the concept. 2 Drag one of the selection indicators. The mouse pointer changes to , and the size of the concept changes.

Drag a corner selection indicator to change the width and the height at the same time.

The number of available ports on a selected concept depends whether the concept was resized or not.

Ports on Default-Sized Concept

Ports on Resized Concept

6.8

Changing the Parent of a Concept

While a concept is in analysis stage, you can detach it from its parent concept and attach it to a different parent.

The new parent must exist in all concept models where this concept exists. In addition, if the concept exists in other currently opened models, reload those models after the change is made.

To change the parent concept:

1 Select the link between the concept and its current parent. The dependent concept must be in the analysis stage. 2 Choose EditReattach. The mouse pointer changes to 3 Click on the new parent. .

6.9

Changing the Type of a Concept

While a concept is in the analysis stage, you can change its type. The concept retains any fields, rules and dependents which have been defined for it. You can change the concepts parent(s) at the same time if you wish.

6-4

Working with the Concept Model Changing the Connector Ports of a Concept

If the concept exists in another currently opened model, reload that model after the change is made.

To change the concept type:

1 Select the concept whose type you want to change. 2 Choose EditChange Type. The Change Concept Type dialog box is displayed.

3 Click the arrow by the Type text box and choose a new concept type. If the concept has fields, which are incompatible with the document concept type (a document may have only a numeric key field and a character field), you cannot change it to a document. 4 Even if you wish to leave the concept attached to the same parent concept, you must list the parent in the Parents text box. (For an association you must specify both parents.) Use the Select button to choose from a list of all concepts in the model. 5 Choose OK. The concept definition dialog box appropriate to the new concept type is displayed. You can change the concepts definition if necessary.

6.10 Changing the Connector Ports of a Concept

You can choose to have a connector line touch the concept at a different place. The following procedure is for changing to a different connector port on the same concept. If you want to attach a concept to an entirely different concept, use EditReattach.

6-5

Working with the Concept Model Exporting a Concept Model to an External UML Tool

To change the connector ports of a concept: Selection indicators (filled-in squares) appear along the link.

1 Select the connecting link by clicking the line between concepts.

Do not confuse ports with selection indicators .

2 Select the concept whose port you want to change by shift-click. The cursor changes to and connector port crosses appear around the concept.
If you change your mind at this point, and do not want to change the connector port, press <Esc> or click the Abort button.

3 Click on a new port to redirect the connector line to touch the concept at the new port. The link is now attached to the concept at that point.

6.11 Exporting a Concept Model to an External UML Tool

Modeler enables the graphical concept model to be exported to any Unifed Modeling Language (UML) tool that supports XMI 2.1. UML is the industry standard modeling language; it is the set of notations, models and diagrams used when developing object-oriented (OO) systems. UMLlike Modelerenables the analyst to:

build and maintain an organizations application model. define the behavior of significant parts of that application. define the relationships between those parts.

Models can be exported to XMI files when in any of the modeling stages (analysis, design and implementation). Designs created when a concept is in the design or implementation stage are also exported. When concept models are exported to XMI, all associated rules are exported with them. In the XMI file, the following eMerge primitive types are used:

eMergeNumeric eMergeCharacter eMergeDate eMergeZoned eMergePackedDecimal

Domains defined by the user in eMerge are also used as primitive types in the XMI file. Once the XMI file is produced, it can be imported by any external UML tool, such as Enterprise Architect or Altova UModel. The model

6-6

Working with the Concept Model Exporting a Concept Model to an External UML Tool

displayed in the supporting tool is identical to the model built via Modeler. Example: Model viewed via Modeler

Model viewed via Enterprise Architect:

6-7

Working with the Concept Model Exporting a Concept Model to an External UML Tool

From the external UML tool, the rules associated with the exported concept model can also be viewed. Example: In the following figure, a concept model is displayed after being exported to an external UML tool. The exported model, on the left side, includes the rule sets and their relationships to the other entities in the model. The user has selected one rule, Rule 20. On the bottom right side in the Notes pane, a description of the selected rule, as exported from Modeler, appears.

6-8

Working with the Concept Model Exporting a Concept Model to an External UML Tool

To export a concept model to XMI:

1 In Modeler, on the Data tab of the navigation pane, expand the Models node. 2 Right-click the model to be exported and choose Export to XMI. An XMI file is created. The XMI file is stored at: <eMergeClientTools>\db\<catalogID><XX>

The newly created XMI file overwrites any previously existing XMI files for the same model concept.

The file is displayed within Development Workbench:

6-9

Working with the Concept Model Exporting a Concept Model to an External UML Tool

6-10

Chapter 7 Viewing Models

This chapter shows you how to switch back and forth between the local view of the model and the global view, how to define the size and the location of the local view, and how to find a concept. The operations described in this chapter are accessed from the View menu.

7.1

Switching between Local and Global View

When you are building a large model, you may not want to work with the whole model on the screen. Modeler lets you focus in on any section of the model. This view is called the local view. All work is done in the local view. When you open a model, it is the local view that appears. At any time, you can switch to the global view and see the whole model.

Global View
When you are in local view, the View menu contains the Global item, and the View Definition button on the toolbar is not selected. To switch to the global view, choose ViewGlobal or click the View Definition button. The global view has a rectangle superimposed on it, to show what section of the model is currently defined as the local view. You cannot work on the model in global view, as indicated by the fact that most toolbar buttons are dimmed. The only thing you can do is to redefine your local view by changing the rectangle. This is described on page 7-4.

Local View
When you are in global view, the View menu contains the Local item instead of the Global item and the View Defintion button is selected. To switch to local view, choose ViewLocal or click the View Defintion button.

7-1

Viewing Models Changing the Local View

7.2

Changing the Local View

There are several ways to change the local view so that you can focus on a specific part of the model:

You can zoom in or out, to change the size of the local view without shifting the focus. Without changing the size of your view, you can shift the focus by using the scroll bars or by specifying a particular point or object that you want to place at the center of the window. To change the size and the focus, you can draw a rectangle from either the current local view or from the global view.

Each of these methods is described in this section.

Zooming In and Out

You can increase or decrease the magnification of your local view: Press the plus key (+) on the keypad to increase magnification by 10% and make the objects and labels larger. (Alternatively, you could choose ViewZoom In or choose the Zoom In button.) Press the minus key (-) on the keypad to decrease magnification by 10% so that more of your model can be seen in the local view. (Alternatively, you could choose ViewZoom Out or click the Zoom Out button.) Click the Normal View button to zoom to normal view. (Alternatively, you could choose ViewZoom to Normal or click the Zoom to Normal button.)

Shifting your View with the Scroll Bars

Shift the local view by using the vertical and horizontal scroll bars which appear on the model window.

Focusing on a Particular Point

When you choose a point to be at the center of the window, the size of the local view remains the same, and the location is shifted. 1 Choose ViewFocus on Point. The mouse pointer changes to 2 Click to focus on the desired area. .

7-2

Viewing Models Changing the Local View

Focusing on a Particular Model Object

When you choose a particular model object to be at the center of the window, the size of the local view remains the same, and the location is shifted. 1 Select the particular model object. If you can find the particular model object in the current local view, click on it. If the particular model object is not in the current local view, or if your model contains many objects, you can search for the object. Refer to "Finding a Particular Model Object" on page 7-4. 2 Choose ViewFocus on Object.

Defining a Local View within the Current Local View

If you wish to redefine your local view to a view within the current local view, you can do it from the current local view. To get a new local view that extends beyond the current local view, except for a simple Zoom Out, you must first switch to global view as described on page 7-1. 1 Choose ViewZoom by Window or choose the Zoom by Window button. The mouse pointer changes to . 2 Point and drag to define a new local view. The local view changes to the rectangle you have drawn.

7-3

Viewing Models Finding a Particular Model Object

Defining a Local View from the Global View

To get a new local view that extends beyond the current local view, except for a simple Zoom Out, you must first switch to global view. If you wish to redefine your local view to be within the current local view, you can do it from the current local view as described on page 7-3. 1 Switch to global view. You will see the whole model, with a rectangle around the area of the current local view. This rectangle has a small square at the upper right hand corner, and a plus sign (+) in the center. 2 Drag the plus sign to move the rectangle so that the lower left corner is where you want it. 3 Drag the small square to stretch the rectangle until the upper right corner is where you want it. 4 Return to local view.

7.3

Finding a Particular Model Object

To find a particular model object:

7-4

Viewing Models Finding a Particular Model Object

1 Choose EditFind or click the Find button. The Find dialog box opens:

2 Click the arrow and choose the type of model object you want. 3 Select the model object from the list. 4 Click the OK button. The Find dialog box closes and the chosen model object appears selected in the model.

If the model object was not displayed in the window, the local view changes to display it at the center.

If there is more than one occurrence of the same object, you can use Edit Find Next to advance to the next occurrence.

7-5

Viewing Models Finding a Particular Model Object

7-6

Chapter 8 Printing and Generating Reports

This chapter describes how you can print the graphic representation of your model, and how you can generate reports.

8.1

Printing a View of a Model

You can print the whole model on one page, or print the current local view on one page. By using the grid, you can print the current local view on several pages.

Printing the Whole Model or the Local View on One Page

1 Choose ModelPrint or click the Print button. The Print dialog box opens:

2 Select Print Current View or Print the Whole Model. 3 Click the Print button to print.

8-1

Printing and Generating Reports Printing a View of a Model

Printing the Current Local View over Several Pages

1 Toggle ModelShow Grid on. A grid is superimposed on the current view of the model. Each rectangle of the grid represents a printed page.

2 Drag the plus sign (+) to move the inner rectangle so that the lower left hand corner is where you want it. 3 Drag the sizing square until the upper right corner is where you want it. 4 After setting the grid the way you want it, leave Show Grid toggled on.

8-2

Printing and Generating Reports Modeler Reports

5 Choose ModelPrint or click the Print button. The Print dialog box opens:

If Show Grid is on, the only view of the model that can be printed is Print Current View by Grid.

6 Click the Print button to print. 7 Toggle ModelShow Grid off when you have finished printing.

8.2

Modeler Reports
Modeler reports are available on several levels:

Constituents of the Current Model

Choose ModelReportsCurrent for a concept model or ModelReports for a rules or presentation model, to get information about the constituents of the current model.

Selected Concept
Select a concept in a model and click the Reports button, to get information about the selected concept. The Concept Information (2062) menu is displayed.

8-3

Printing and Generating Reports Modeler Reports

Enterprise Model
Choose ModelReportsEnterprise for a concept model, to get information about the constituents of the whole enterprise model. You can find a concept even if you do not know its parent objects or the model in which it is included. 1 Open a concept model. 2 Choose ModelReportsEnterprise. The Concept Information (2035) menu is displayed:

3 Choose the Concepts by Name option. A listing of all the enterprises concepts is generated:

8-4

Printing and Generating Reports Modeler Reports

8-5

Enterprise concepts by name --------------------------------------------------------------------| | | | CONCEPT | | NO. | CONCEPT NAME | CONCEPT TYPE | STATUS | --------------------------------------------------------------------| 1 | ACCOUNT DETAILS | ASSOCIATION | ANALYSIS | | 2 | ADDRESS | WEAKENTITY | IMPLEMENT | | 3 | ASSIGNMENT | ASSOCIATION | IMPLEMENT | | 4 | ATTENDANCE | WEAKENTITY | ANALYSIS | | 5 | BANK | ENTITY | IMPLEMENT | | 6 | BRANCH | WEAKENTITY | IMPLEMENT | | 7 | CONTRACT | WEAKENTITY | IMPLEMENT | | 8 | CUSTOMER | ENTITY | IMPLEMENT | | 9 | DATE | DOMAIN | IMPLEMENT | | 10 | EDUCATION | WEAKENTITY | ANALYSIS | | 11 | EMPLOYEE | ENTITY | IMPLEMENT | | 12 | FUNCTION | DOMAIN | IMPLEMENT | | 13 | MONTHLY ATTENDANCE | WEAKENTITY | ANALYSIS | | 14 | MONTHLY TOTALS | WEAKENTITY | ANALYSIS | | 15 | PAYMENT METHOD | DOMAIN | IMPLEMENT | ----------------------------------------------------------------------------------------------------------------------------------------| | | | CONCEPT | | NO. | CONCEPT NAME | CONCEPT TYPE | STATUS | --------------------------------------------------------------------| 16 | PROJECT | WEAKENTITY | IMPLEMENT | | 17 | PROJECT FORM | DOMAIN | IMPLEMENT | | 18 | REVIEW | DOCUMENT | IMPLEMENT | | 19 | SEX | DOMAIN | IMPLEMENT | | 20 | SKILL | WEAKENTITY | IMPLEMENT | ---------------------------------------------------------------------

Printing and Generating Reports Modeler Reports

8-6

Chapter 9 Object Number Selection

Each knowledgebase object has a unique identifying number. The identifying numbers must be chosen from a set of numbers that are valid for the type of object. If you assign the number when creating the object, that number must be chosen from among the valid numbers. If you do not assign a number, eMerge assigns a number from among the valid numbers. A set of valid number ranges is called a rangeset. Instead of explicitly assigning a number when creating an object, you can specify the rangeset from which eMerge should assign the number. Each valid range of numbers is associated with a complexity that indicates the number of dependents that can be placed under a root constructor. Before you begin working with Modeler, ask your administrator which rangeset you should use for your model (i.e. your application).

Rangeset
A rangeset contains allowed number ranges for the various knowledgebase objects: root objects, dependent objects, and associated objects (fields, forms, rulesets, etc.). There is a default rangeset, and you can define private rangesets: System (SYS) Rangeset This is the default set of valid numbers. The SYS rangeset contains all permitted numbers that can be used to identify objects in the knowledgebase. Private Rangeset The administrator can define private rangesets of valid number ranges. Private rangesets allow specific number ranges to be set aside for use in specific applications or in specific parts of an application.

9-1

Object Number Selection

For each implemented concept and each implemented design, a constructor is created. The unique identifying number of the constructor is the constructor number. The constructor number may be chosen by the developer when the constructor is created. Otherwise, the number is chosen automatically from a set of valid numbers included in the definition of the rangeset specified when the concept or design was created. Each rangeset includes a set of number ranges.

Complexity
The complexity of a number range indicates the number of dependents that can be placed under a root constructor. Some number ranges are appropriate for roots with many dependents, and some number ranges are appropriate for roots with few or no dependents. Complexity
VERY COMPLICATED COMPLICATED FLAT Up

Number of Dependents Up to one hundred or more dependents. to ten dependents. Usually no dependents.

A particular rangeset can have more than one range of numbers for a particular complexity. Example: The COMPLICATED complexity can include the following ranges of numbers: 11301970 24002990 51005600
9-2

Object Number Selection

While the FLAT complexity can include the following ranges of numbers: 30009999 1130019799

Determining Identifying Numbers

Before you begin working with Modeler, ask your administrator which rangeset you should use for your model (i.e. your application). When you insert a new model, you select a rangeset and a complexity.

Select the rangeset your administrator assigned to you. Select the complexity for the majority of the root concepts in the model.

If the rangeset and/or complexity are not specified, the SYS rangeset and the COMPLICATED complexity are used by default. Thus, a concept model is created with a particular rangeset and complexity. Any root concept defined in the model is automatically defined, by default, with the models rangeset and complexity. A different rangeset and/or complexity than the one specified for the model can be selected for an entity. The rangeset and complexity of an entity determine its constructor number and the constructor numbers of its dependent concepts (e.g. weak entities). The rangeset determines the identifying numbers of the associated composites, classes, fields, operations, forms, and rulesets of the root concept and its dependent concepts. All entities, main designs, and user designs in a model receive, by default, the rangeset and complexity chosen for the model. Domains and rulesets in a model receive, by default, the rangeset chosen for the model. The rangeset and complexity can be changed from the default, according to the following table: What Can Be Changed root concept physical user design for an entity domain ruleset 3 3 3 Rangeset 3 3 not applicable not applicable Complexity

When Modeler needs to choose a constructor number, it searches for the first available number according to the specified rangeset and
9-3

Object Number Selection Rangeset and Complexity for a Model

complexity. If all the number ranges at a particular complexity are full, an appropriate message is generated. You may choose another complexity or have your administrator allocate more numbers to your rangeset.

9.1

Rangeset and Complexity for a Model

For a New Model
1 From the Data tab, right-click Models and choose New Model. The New Concept Model form is displayed:

2 Enter the needed information for the new model. See "Inserting a New Concept Model" on page 2-2. 3 Select the rangeset in the Rangeset ID listdrop. This is the identifier of the rangeset that you wish to use for the model. 4 In the Complexity listdrop, select the complexity for the majority of the root concepts in the model. The complexity for a particular root concept can be overridden. See "Rangeset and Complexity for an Entity" on page 9-6.

For an Existing Model

Rangeset A model with no concepts You can change the models rangeset.

9-4

Object Number Selection Rangeset and Complexity for a Model

A model with concepts You can changes the models rangeset according to the following:

You can change the rangeset from a private rangeset to SYS. You cannot change the rangeset from a private rangeset to another private rangeset. You can change the rangeset from SYS to a private rangeset. Depending on the stage of the entities in the model, a proposed change to the rangeset has the following results: For entities in the analysis or design stage: The rangeset is changed to the new rangeset if the complexity assigned to the entity exists in the new rangeset. Otherwise, the rangeset is not stored and an appropriate message is issued. For entities in the implementation stage: Implementation of an entity means the constructor numbers for the entity, its dependents and associated objects have all been chosen. When the rangeset is changed, the identifying numbers are checked. If they are within the number ranges of the proposed rangeset, the rangeset is changed. Otherwise, the models rangeset cannot be changed and an appropriate message is issued.

Complexity

You can change the complexity of an existing model. Changes made only affect concepts added to the model after the change takes place. That is, changes do not affect any concepts already in the model. Nor do any changes affect concepts that are defined in other models and included in this model. Changing the complexity for a model is useful if a model includes concepts with various numbers of dependents. Example: For a model with concepts that have many dependents and concepts with no dependents. You may first specify a VERY COMPLICATED complexity. After the concepts with many dependents are defined, change the models complexity to FLAT.

9-5

Object Number Selection Rangeset and Complexity for an Entity

Changing the Rangeset and/or Complexity

Use the following procedure to change the rangeset and/or complexity of an existing model: 1 Via Modeler, choose ModelProperties. The Concept Model Details form is displayed:

2 Select the rangeset in the Rangeset ID listdrop. This is the identifier of the rangeset that you wish to use for the model. 3 In the Complexity listdrop, select the complexity for any entities added to the model. The complexity for a particular entity can be overridden (see "Rangeset and Complexity for an Entity" on page 9-6).

9.2

If the new rangeset does not have the complexity assigned to the entity, the rangeset is not stored and an appropriate message is generated. If the identifying numbers for the entity, its dependents and associated objects are not within the number ranges of the new rangeset, the models rangeset cannot be changed and an appropriate message is generated.

Rangeset and Complexity for an Entity

A particular entity does not have to have the same rangeset and complexity that was specified for entities in the model. You may force Modeler to choose a constructor number for an entity from a different rangeset and/or complexity than the one specified for the model:

You can change rangeset from SYS to a private rangeset. You can change complexity to any valid complexity for the rangeset.

Any specification to the rangeset and complexity is reflected in the entitys dependent concepts and all its associated objects. For an
9-6

Object Number Selection Rangeset and Complexity for an Entity

association, the rangeset and complexity of the main parent are reflected in the Main design. The rangeset and complexity of a non-main parent are reflected in the OppositeToMain design. Example: A complexity of COMPLICATED was specified for the model. However, you have a particular entity that will have many more dependents than the default for concepts in the model. Specify the complexity to be VERY COMPLICATED for the particular entity. The rangeset and complexity for an entity can only be specified (i.e. overriding the default from the model) or changed if the entity is not implemented.

To specify or change the rangeset and complexity for an entity:

1 Via Modeler, select the concept (it must be in analysis or design) and click the Fields button. The Concept form is displayed:

2 In the Rangeset ID listdrop, select the rangeset for the concept. You can change the rangeset from SYS to a private rangeset. 3 In the Complexity listdrop, select the complexity for the concept.

9-7

Object Number Selection Complexity for a User Design

9.3

Complexity for a User Design

A physical user design (one created by the user, not the Main design) for an entity does not have to have the same complexity as the main design of the entity. You may force Modeler to choose a constructor number from a different complexity than the one specified for the entity. (The rangeset for a user design cannot be changed.) Example: A physical user design has no dependents (FLAT), while the Main design has very many dependents (VERY COMPLICATED). The complexity for a user design can only be changed, if the user design has not been implemented (i.e. the Implementation option was not assigned to the design).

To change the complexity for a user design:

1 Via Modeler, right-click the concept and choose Object > Concept Design. The Concept: Design form is displayed. 2 Click AllDesigns. The Concept: All Designs form is displayed. 3 With the insertion point in the design needed, click the Definition button. The Concept: Design Definition form is displayed. 4 Click Advanced. The Design Advanced form is displayed:

5 In the Complexity listdrop, select the complexity for the design.

9-8

Object Number Selection Rangeset for a Domain

9.4

Rangeset for a Domain

There are two ways to define a domain (See "Domain Concept" on page 3-7.) The way the domain is defined determines the default rangeset for the domain: Via the Concept Model When a domain is defined via the concept model, the rangeset for the domain is taken from the models rangeset. Via the Concept When a domain is defined via the concept, the rangeset is taken from the concepts rangeset.

Changing the Default Rangeset

The rangeset of a domain can be changed from the default one taken from the model or concept. That is, while defining the domain, you can specify a rangeset other than the default.

To specify the rangeset for a new domain defined via the concept model:

1 Choose InsertDomain. The New Domain form is displayed:

2 Enter the needed information for the new domain (see "Defining a Domain" on page 3-8). 3 In the Rangeset ID listdrop, select the rangeset for the domain. You can change the rangeset from SYS to a private rangeset.

9-9

Object Number Selection Rangeset for a Domain

To specify the rangeset for an existing domain defined via the concept model:

1 Choose ObjectsAll Domains. The All Domains form is displayed:

2 Put the pointer on the domain you want to change and click the Definition button. The Domain Definition form is displayed:

3 In the Rangeset ID listdrop, select the rangeset for the domain. You can change the rangeset from SYS to a private rangeset.

9-10

Object Number Selection Rangeset for a Ruleset

To specify the rangeset for a domain defined via the concept:

1 Select a concept and click the Fields button. The Concept form is displayed. 2 For a new domain, enter a new domain name in the Domain field while you are defining a field. The domain is created automatically. Or For an existing domain, put the pointer on the domain you want to change. 3 Click the Domain button. The Domain Definition form is displayed. 4 Enter the needed information for the new domain (see "Defining a Domain" on page 3-8). 5 In the Rangeset ID listdrop, select the rangeset for the domain. You can change the rangeset from SYS to a private rangeset.

Changing the Domain Rangeset While Changing the Concept Rangeset

When the rangeset for a concept is changed from SYS to a private rangeset, the rangeset for the domain defined via the concept is changed too. If the domain has been implemented, the domain field number is checked against the new rangeset. If the field number does not exist within the allocations of the new rangeset, the rangeset for the domain is not changed.

9.5

Rangeset for a Ruleset

Rulesets are identified by a unique number (i.e. a ruleset number). The ruleset number may be chosen by the developer or chosen automatically. When the ruleset number is chosen by the developer, the number must be an allowed number. When the ruleset number is chosen automatically, the number is determined by the rangeset.

Rulesets with a Triggering Object

When you create a ruleset with a triggering object, you cannot select a rangeset for the ruleset.

If the triggering object is a concept or a design, enter a name for the ruleset. The ruleset number is chosen automatically according to the
9-11

Object Number Selection Rangeset for a Ruleset

rangeset of the concept or the design, respectively. This is true for user-defined rulesets as well as automatic rulesets.

If the triggering object is a block in a form, an operation, a program, a query, or a class in a composite, enter a name for the ruleset and choose an allowed number that is not in use as the ruleset number.

See "Creating a Ruleset with a Triggering Object" on page 11-5.

Rulesets without a Triggering Object

You can create a ruleset without a triggering object either via Modeler or via the Ruleset Definition form.

Via Modeler When working with the rule model of a concept, enter a name for the ruleset. The ruleset number is chosen automatically according to the rangeset of the root concept. When working with the rule model of a block in a form, an operation, a program, a query, or a class in a composite, enter a name for the ruleset and a ruleset number. See "Creating a Ruleset without a Triggering Object" on page 11-10. Via the Ruleset Definition form Enter a name for the ruleset. Then, either choose an allowed number that is not in use as the ruleset number, or select a rangeset for the ruleset. The ruleset number is chosen automatically from the number ranges defined for rulesets for the particular rangeset.

9-12

Object Number Selection Working with Privacy

To specify a rangeset for a ruleset without a triggering object via the Ruleset Definition form:

1 On the Logic tab, right-click the Rulesets node and choose New Ruleset. The Ruleset Definition form is displayed:

2 Enter the Name of the ruleset. 3 In the Rangeset ID listdrop, select the rangeset for the ruleset. 4 Continue entering the needed information. See "Creating a Ruleset without a Triggering Object" on page 11-10.

9.6

Working with Privacy

If security is active, the administrator can define your user privacy. The user privacy can be defined via private rangesets. When your user ID is assigned to a particular rangeset, you can only use identifying numbers allowed by the assigned rangeset. That is, the assigned rangeset determines constructor numbers for root concepts and their dependent concepts. The assigned rangeset also determines the identifying numbers of the associated fields, forms, and rulesets for roots and their dependents.

9-13

Object Number Selection Working with Privacy

You can be assigned to more than one private rangeset (while a particular private rangeset can have more than one user assigned to it). When working via Modeler, you can work with concept models that are defined with a rangeset not allowed for your user ID. You can:

openfor view onlyconcept models that defined with a not-allowed rangeset openfor view onlythe definition of concepts defined with a notallowed rangeset include concepts defined with a not-allowed rangeset in your models, but no changes may be made to the concept define associations between your own concepts and concepts that are defined with a not-allowed rangesethowever only if the not-allowed concept is not a main parent

9-14

Part C

Logic

Chapter 10 What is Logic

Logic increases the functionality of an application by providing for computations, validation of data values, moving data between data objects, conditional checking, creating eMerge components, as well as invoking external programs. There are two basic types of logic: Built-in application logic User-defined application logic

10.1 Built-in Application Logic

eMerge has built-in application logic that automatically performs various verifications and checks when implementing an application. These include:

Different roles of fields in an operation Example: Verification of a field in the operation against its value in the target occurrence.

Primary key-based referential integrity constraints: update rules resulting from the hierarchical structure of objects in the database Example: An independent occurrence of a data object must exist in order to insert a dependent occurrence.

Validity checks that are driven by field definitions Example: Numerical value, date value, length, possible values, check digit, referential integrity constraints based on nonprimary keys, etc.

Checking that is driven by the role of the field in an operation Example: A check for existence of mandatory fields in the operation. Update rules triggered by the operation code in an operation Example: In order to change an occurrence of a data object, the occurrence must exist.

10-1

10

What is Logic User-defined Application Logic

10.2 User-defined Application Logic

The following are provided by eMerge for defining logic for an application:

Options Rules Built-in functions User-defined functions (i5/OS only) External programs: called online, called in batch

When defining the logic for an application, try to follow the order listed above to maximize the efficiency of the logic used for the application. Whenever possible, use options rather than writing rules or running external programs. Often the same result can be achieved using different methods.

Options
Options are the fastest logic that can be included in an application. Options are used to modify a default action or to provide functionality that is not dependent on a specific value in the database. Modifying a default action: For example, the default action upon encountering an error is to issue an error message and to terminate processing. By assigning the Warning option, the error message is suppressed, and instead, a warning message is issued and processing continues. Provide functionality independent of a value in the database: For example, assigning the Fromkey option to a field in a concept provides copying functionality, not related to the specific value to be copied.

Rules
Logic that cannot be handled by an eMerge option, can be handled by defining a rule model (see "Rule Model" on page 10-3). The rule model is defined using Modeler, a development tool of Development Workbench. A rule model contains one or more rulesets. Each ruleset contains one or more rules. The rules are written in a declarative language which allows referencing eMerge built-in functions, as well as calling user-defined functions. Using functions within rules is a fast way to perform logical processes.

10-2

What is Logic Rule Model

Built-in Functions

eMerge built-in functions perform a spectrum of calculations that make the composing of business rules much easier. By using built-in functions rule composure time is shortened, rule statements are more compact, and development time is saved. Built-in functions are divided into function categories for easier referencing. For example, there are Mathematical functions (e.g. Round, Power,...), String manipulation functions (e.g. Reverse, StringCompare,...), Date functions (e.g. MonthOfDate, YearOfDate,...), Time functions (e.g. TimeSubtract, TimeAdd,...) and General functions. Functions defined by the user that call a user function written in C when working in i5/OS, HP-UX, or Linux.

User-defined Functions i5/OS HP-UX Linux

External Programs
External programs in eMerge can be written in any of the following languages: z/OS, z/VM COBOL, DBCOBOL, PL/I, DBPL1, IBM Assembler COBOL, DBCOBOL, C

i5/OS, HP-UX, Linux

See Chapter 60, Calling C Programs from eMerge Under i5/OS, HP-UX and Linux. DBCOBOL and DBPL1 are standard COBOL and PL1 languages with 4GL extensions to access the eMerge database. They can be executed in batch mode or online within an eMerge session. Use external programs in the following circumstances:

Time-dependent processing (i.e. end of year processing). Functions that utilize external code modules (i.e. common date or tax routines). Complex reporting outside the scope of the eMerge query language.

10.3 Rule Model

The eMerge rule model is a collection of one or more rulesets. A ruleset, in turn, is a collection of rules, that together, describe a business rule.

10-3

10

What is Logic Rule Model

Rulesets
A ruleset has triggering objects and triggering events. Triggering Objects A ruleset is attached to an object defined in the knowledgebase. This object is referred to as the triggering object for the ruleset. The triggering object for a ruleset may be one of the following:

A data object (i.e. a concept, a constructor, a class) A presentation object (i.e. an operation, a block in a form, a program, or a query).

Triggering Events

Triggering a ruleset executes the rules in the ruleset. A ruleset is triggered when the following occurs:

A field in a constructor occurrence is updated (i.e. inserted, changed or deleted). A message (i.e. operation) is issued.

10-4

What is Logic Rule Model

A presentation object (i.e. a block in a form) is manipulated. A program or query is executed. An error occurs.

Development Stages
The rule model is built by, choosing and positioning on the display, graphic symbols for the rulesets, the rules within the rulesets, and the connectivity between the rulesets and their triggering objects. Each ruleset in the model contains a rule or a collection of rules. Each rule in a ruleset is in one of the following development stages:

Analysis Design Implementation

In a single model, you can have rules in all of these development stages. The current stage of a rule is represented by the color and pattern of the rules graphic symbol in the model, so you can tell at a glance how development is progressing. Analysis In the analysis stage you define the rulesets (and their rules), by choosing: the graphic symbols that represent the type of the ruleset, the location of the rules in the ruleset, and the connectivity between the ruleset and its triggering object. When a rule is in the analysis stage, the default symbol for the rule is blue with no pattern.

Design

Choose View > OptionsSymbols to change the color and pattern for symbols in the rule model.

In the design stage you compose the content of each rule in the ruleset. The rules are written using query. When a rule is in the design stage, the default symbol for the rule is yellow with no pattern.

Implementation

In the implementation stage you compile the rules. Once implemented, the rule is defined in the eMerge knowledgebase, and during runtime, if triggered, it is executed. When a rule has been implemented, its symbol changes color to green.

10-5

10

What is Logic Rule Model

Rule Model Logic

Modeled The rule model, with all its rulesets and rules, is diagrammed and displayed to the developer using Modeler. The connections between the rules and the objects they operate on are clearly visible. Changes are made to the model by moving elements on the display. This greatly facilitates developing and understanding complicated applications. Rule statements in a conventional program are grouped together and executed in sequence. The same business rule must therefore be repeated in every program where it is required. In eMerge, the rule is defined only once and attached to a data or presentation definition. Thus, if any change to the rule is required, it is made in one place rather than in many. The rule is invoked for any action performed on the data or presentation definition. In an application the developer must explicitly treat every business situation that may arise. In eMerge, only the expected situation is treated. At development time, this greatly lowers the time spent on rule development (the expected situation represents a small subset of all the possible situations). At runtime, this reduces the time spent in rule processing (the expected situation is the one most often encountered). Rule definitions, by default, include no reference to the operation code (insert, change, delete, edit or any of the other retrieval operations). eMerge automatically decides what actions to take, based on the operation code. For example, for an Insert operation, the rule should only relate to the expected case of the regular insert situation. The rest of the situations (the consequences of the insert operation) are automatically dealt with by eMerge by inference from the expected case. Example: When an item is ordered, in an order entry system, the quantity ordered must be subtracted from the quantity in stock. The expected or normal case is one of ordering an item and the rule looks similar to the following (the exact syntax has been altered for purposes of clarity): quantity is subtracted from stock. eMerge automatically infers the rules required to handle the implications that occur if changes or deletions are made to the order. The following table lists some results inferred by eMerge for several edit operations:

Non-redundant

Situation Independent

10-6

What is Logic Rule Model

Operation Change Change Change

Case quantity ordered is decreased by n quantity ordered is increased by m item ordered is replaced with a different item order is cancelled add n to stock

Result subtract m from stock add quantity ordered to item in stock and remove quantity from new item in stock add quantity ordered to stock

Delete

10-7

10

What is Logic Rule Model

10-8

Chapter 11 Analysis Stage: Building a Rule Model

The rule model is built by choosing and positioning graphic symbols: for the rulesets, for the rules within the rulesets and for the connectivity between the rulesets and their triggering objects. A rule model can be opened from either a concept, constructor, class, operation, block in form, query or program.

11.1 Rulesets
A ruleset is a container that holds a rule or a set of rules that describe a business rule. During analysis, you identify the rulesets and their rules. The information you define about each ruleset includes the following:

The name of the ruleset. How the ruleset is used. Documentation of what the ruleset is intended to do.

Example: For the Employee concept, there might be a ruleset containing rules that deal exclusively with salary considerations, and another ruleset that deals with the employee work schedule. Each ruleset is independent of the other, although both are triggered when an event occurs to the Employee concept. A ruleset can be created via a triggering object or independent of a triggering object. If a ruleset is created independent of a triggering object, it must eventually be attached to a triggering object. The ruleset is encapsulated together with its triggering object. Manipulation of a triggering object causes execution of the rules in the ruleset attached to the object.

11.2 Triggering Object

A ruleset is executed when an event occurs to its triggering object. The triggering object to which the ruleset is attached can be one of the following:
11-1

11

Analysis Stage: Building a Rule Model Triggering Object

data object (e.g. concept, constructor, or class within a composite) presentation object (e.g. operation, or block in form) message object (e.g. query, or program)

Data Object
Concept A ruleset attached to a concept is executed when the concept is updated (i.e. user action or data update). When you define a ruleset that is attached to a concept, you must define the kind of ruleset; i.e. its usage. There are two types of usage for a ruleset attached to a concept: constraint and consequence. Constraints are always activated (triggered) before consequences. Constraint Rulesets that determine whether or not the user action or data update is valid. These are validations that are not covered by Basic Path features such as the correspondence between data type and value. For example, an employee must be over eighteen years of age to be hired. Consequence data update. Rulesets that change data because of some user action or

For example, when a quantity of items is sold to a customer, that quantity is deducted from the items in inventory. Constructor A ruleset attached to a constructor is executed when the constructor is updated. The constructor is equivalent to the implementation of a design of a concept. A ruleset attached to a class within a composite is executed when the class within a composite is updated. The class within a composite is the internal representation of a concept.

Class within a Composite

Presentation Object
Operation There are two kinds of rulesets that can be attached to an operation: issue or edit. Issue Rulesets that are executed (triggered) when an operation is issued, before the operation (insert, change, edit etc.) is performed and before edit rulesets are executed. Edit Rulesets that are executed when an editing operation is performed; i.e. when an operation issued with the Edit operation code or

11-2

Analysis Stage: Building a Rule Model Ruleset Triggering Order Within a Model

when scrolling on the block is done (using the Backward or Forward buttons).

Block in a Form

An edit ruleset cannot be run in batch, because the function of an edit ruleset is to enhance the presentation of the data on a form.

When you want a ruleset to be executed in only certain executions of an operation, program or query, attach the ruleset to a block in a form, and not directly to an operation, program or query. The ruleset is executed according to the same criteria as a ruleset attached directly to an operation, program or query, except that the ruleset is only executed online. Rulesets attached to a block that is used to display the results of a query are not executed when the query output is displayed. To execute the rulesets when query output is displayed, they should be attached to the query and not to the block.

Message Object
A ruleset attached to a program or query is executed before any parameters are passed to the program or query. Thus, a ruleset can be used to calculate the necessary parameters for the program or query.

11.3 Ruleset Triggering Order Within a Model

Position
The position you choose in the rule model for locating the graphic symbol representing a ruleset determines the order in which the ruleset is triggered (i.e. executed).

Usage
For some triggering objects, you must define the usage of the ruleset. The usage is identified in the rule model by the symbol displayed on the line above the ruleset symbol. A ruleset having a constraint usage is triggered before a ruleset having a consequence usage. The ruleset with a constraint usage is always located to the left of the ruleset with a consequence usage.

11-3

11

Analysis Stage: Building a Rule Model Ruleset Triggering Order Within a Model

The following table lists the triggering objects that have usage. Included in the table are the symbols displayed in the rule model to indicate the usage of the ruleset: Triggering Object Concept Symbol Usage constraint consequence Operation issue edit If you insert a ruleset within another ruleset that has its usage already defined, the inserted rulesets usage is determined automatically. However, if a ruleset is the first ruleset belonging to a triggering object, or if you insert a ruleset between two kinds of rulesets (rulesets with different usages), you must select the usage for the inserted ruleset.

Example of Position and Usage

In the rule model below, Validity Checks is a constraint ruleset and Computations and Updates are consequence rulesets. The ruleset execution order is: Validity Checks, Computations, and Updates.

If a new ruleset is inserted to the left of Validity Checks, it is automatically set as a constraint. If, on the other hand, it is inserted to the right of Computations, it is automatically set as a consequence. However, if you insert the new ruleset between Validity Checks and

11-4

Analysis Stage: Building a Rule Model Triggering Order for Rulesets Attached to Different Objects

Computations, you must select the usage for the new ruleset when you insert the ruleset in the model.

11.4 Triggering Order for Rulesets Attached to Different Objects

When a change of state triggers rulesets attached to different triggering objects, the following is the order for executing the rulesets: 1. Rulesets attached to a block in a form. 2. Issue rulesets or rulesets attached to a program or query. 3. Edit rulesets. Issue rulesets are executed before edit rulesets to retrieve the data from the database used in the editing. 4. Rulesets attached to a concept or a constructor.

11.5 Creating a Ruleset with a Triggering Object

Triggering Object is a Concept
1 Via Modeler, select the concept and click the Rules button. The rule model for the concept is displayed. 2 Select the triggering concept by clicking its graphic symbol in the rule model display. If the triggering concept is in the design or implementation stage, select the design of the concept. If there is more than one concept design, select the one you want. 3 Click the Ruleset button on the toolbar. If this is the first ruleset under the triggering concept or concept design, the position of the ruleset is determined automatically. If there are already rulesets under the triggering concept or concept design, the mouse pointer changes to , and the status line prompts you to choose a position. Click on the position among the siblings where you want to place the ruleset. The position you choose in the rule model for the ruleset determines the order in which the ruleset is triggered. See "Ruleset Triggering Order Within a Model" on page 11-3 for more information. The ruleset symbol appears under the triggering concept or concept design and the Ruleset dialogbox opens.

11-5

11

Analysis Stage: Building a Rule Model Creating a Ruleset with a Triggering Object

4 Enter the name of the ruleset in the Name textbox. The name must be unique.

A ruleset number is not needed because the ruleset number is based on the Constructor Number of the root concept (see "Object Number Selection" on page 9-1).

5 If the usage is not determined automatically by the position of the ruleset, select the usage needed (i.e. Constraint or Consequence). 6 Click the OK button. The ruleset is displayed in the model:

Triggering Object is a Form

1 Using Form Editor, access the Form Definition form (see Part E Presentation for more information on forms). 2 Click the Rule Model button. The rule model for the form is displayed.

11-6

Analysis Stage: Building a Rule Model Creating a Ruleset with a Triggering Object

3 Select the triggering block by clicking its graphic symbol in the rule model display. 4 Click the Ruleset button on the toolbar. If this is the first ruleset under the triggering block, the position of the ruleset is determined automatically. If there are already rulesets under the triggering block, the mouse pointer changes to , and the status line prompts you to choose a position. Click on the position among the siblings where you want to place the ruleset. The position you choose in the rule model for the ruleset determines the order in which the ruleset is triggered. See "Positioning a Rule" on page 11-22 for more information. The ruleset symbol appears under the triggering block and the Ruleset dialogbox opens. 5 Enter the name of the ruleset in the first textbox of the Name field and the number of the ruleset in the second textbox of the Name field:

The ruleset number must be an allowed number that is not already in use a ruleset number. The following are the valid identifying numbers for rulesets: 30009999 1130019799 2400029999 5100056000 9300099000 113000197999 240000999999

11-7

11

Analysis Stage: Building a Rule Model Creating a Ruleset with a Triggering Object

6 Click the OK button. The ruleset is displayed in the model:

Triggering Object is a Class in a Composite, an Operation, a Program, or a Query

1 From the Navigation Pane, access the triggering object definition form. For instance, if the triggering object is a class in a composite, open the Class Definition form. 2 Click the RuleModel button on the triggering object definition form. The rule model for the triggering object is displayed. 3 Select the triggering object by clicking its graphic symbol in the rule model display. 4 Click the Ruleset button on the toolbar. If this is the first ruleset under the triggering object, the position of the ruleset is determined automatically. If there are already rulesets under the triggering object, the mouse pointer changes to , and the status line prompts you to choose a position. Click on the position among the siblings where you want to place the ruleset. The position you choose in the rule model for the ruleset determines the order in which the ruleset is triggered. See "Positioning a Rule" on page 11-22 for more information. The ruleset symbol appears under the triggering object and the Ruleset dialog box opens.

11-8

Analysis Stage: Building a Rule Model Creating a Ruleset with a Triggering Object

5 Enter the name of the ruleset in the first textbox of the Name field and the number of the ruleset in the second textbox of the Name field:

The ruleset number must be an allowed number that is not in use as the ruleset number. The following are the valid identifying numbers for rulesets: 30009999 1130019799 2400029999 5100056000 9300099000 113000197999 240000999999 6 For a triggering operation, If the usage is not determined automatically by the position of the ruleset, select the usage needed (i.e. Issue or Edit). 7 Click the OK button. The ruleset is displayed in the model:

11-9

11

Analysis Stage: Building a Rule Model Creating a Ruleset without a Triggering Object

11.6 Creating a Ruleset without a Triggering Object

A ruleset can be created independent of a triggering object and later attached to a triggering object.

Within a Rule Model

1 Access the rule model of the triggering object. 2 Click the Ruleset button on the toolbar.

Do not select the triggering object.

The mouse pointer changes to choose a position.

, and the status line prompts you to

3 Click in the model. The ruleset symbol appears and the Ruleset dialogbox opens. For a rule model of a concept Name textbox. Enter the name of the ruleset in the

For a rule model of a class in a composite, a block in a form, an operation, a program, or a query Enter the name of the ruleset in the first textbox of the Name field and the number of the ruleset in the second textbox of the Name field. The ruleset number must be an allowed number that is not in use as the ruleset number. The following are the valid identifying numbers for rulesets: 30009999 1130019799 2400029999 5100056000 9300099000 113000197999 240000999999 4 Click the OK button. The ruleset is displayed in the model. 5 Select the ruleset and click the Ruleset button on the toolbar. 6 The rule model for the ruleset is displayed.

11-10

Analysis Stage: Building a Rule Model Creating a Ruleset without a Triggering Object

Via the Ruleset Definition Form

1 Click the Logic tab in the Navigation Pane. The Logic tab is opened.

2 Right-click Rulesets. A pop-up menu appears.

11-11

11

Analysis Stage: Building a Rule Model Creating a Ruleset without a Triggering Object

3 Choose New Ruleset. The Ruleset Definition form is displayed.

4 Enter a name for the ruleset in the Name textbox. 5 Enter a number for the ruleset in the Ruleset No. textbox, or select a rangeset for the ruleset in the Rangeset ID field. The ruleset number must be an allowed number that is not in use as the ruleset number. The following are the valid identifying numbers for rulesets: 30009999 1130019799 2400029999 5100056000 9300099000 113000197999
11-12

Analysis Stage: Building a Rule Model Attaching a Ruleset to a Triggering Object

240000999999 6 Click Apply to save the information. 7 Click OpenModel to view and modify the rule model for the ruleset.

11.7 Attaching a Ruleset to a Triggering Object

A ruleset can be created via a triggering object or independently of a triggering object. Eventually, you must attach the ruleset to a triggering object. A ruleset is attached to a triggering object via the rule model of the triggering object. That is, by opening the rule model for a triggering object and creating a new ruleset or inserting an existing ruleset, you are attaching a ruleset to a triggering object.

To attach an existing ruleset to a triggering object:

1 From the Navigation Pane, access the triggering object definition form. For instance, if the triggering object is a class, open the Class Definition form. If the triggering object is a concept, access its rule model via Modeler. If the triggering object is a block in a form, access its rule model using Form Editor.

2 Click the RuleModel button on the triggering object definition form. The rule model for the triggering object is displayed. If the triggering object is a concept, select the concept and click the Rules button to display the rule model. 3 Select the triggering object by clicking its graphic symbol in the rule model display. If the triggering object is a concept in the design or implementation stage, select the design of the concept. If there is more than one design, select the one you want. 4 Click the Ruleset button on the toolbar. If this is the first ruleset under the triggering object, the position of the ruleset is determined automatically. If there are already rulesets under the triggering object, the mouse pointer changes to , and the status line prompts you to choose a position. Click on the position among the siblings where you want to place the ruleset. The position you choose in the rule model for the

11-13

11

Analysis Stage: Building a Rule Model Viewing or Modifying a Ruleset Rule Model

ruleset determines the order in which the ruleset is triggered. See "Positioning a Rule" on page 11-22 for more information. The ruleset symbol appears under the triggering object and the Ruleset dialog box opens. 5 Click Include to attach the existing ruleset. All the rules defined for the ruleset are included along with it. 6 Click Find. The Ruleset List dialogbox opens:

7 Select the ruleset you want to attach and click OK. 8 The name and number of the ruleset are displayed in the Ruleset dialogbox (if the triggering object is a concept, only a name is displayed). 9 If the usage is not determined automatically by the position of the ruleset, select the usage needed (e.g. Constraint or Consequence). 10 Click the OK button. The ruleset is displayed in the model.

11.8 Viewing or Modifying a Ruleset Rule Model

A ruleset can be viewed or modified within the rule model of its triggering object or within a rule model of the ruleset itself. the latter is true whether the ruleset has triggering objects or not.

11.9 Documenting a Ruleset

During analysis, besides defining each ruleset, document what the ruleset is intended to do. 1 Click the ruleset that you want to document.

11-14

Analysis Stage: Building a Rule Model Displaying Ruleset Information

2 Choose ObjectDocumentation. The Ruleset Documentation (200011) form is displayed with the name of the ruleset displayed in the Ruleset field.

3 Enter the documentation text in the Documentation groupbox. 4 When you are finished, click the OK button to return to the model window.

11.10 Displaying Ruleset Information

You can obtain information on all the rulesets in rule model or information on a particular ruleset in the rule model.

Displaying Information on all Rulesets in the Rule Model

You can obtain information on all the rulesets in the rule model:

11-15

11

Analysis Stage: Building a Rule Model Defining Rules for a Ruleset

Position the pointer in the rule model (not on a graphic symbol) and click the Reports button. The Ruleset Information menu is accessed:

Displaying Information on a Particular Ruleset in the Rule Model

You can obtain information on a particular ruleset in the rule model: 1 Select the particular ruleset graphic symbol form the rule model. 2 Click the Reports button. The Ruleset Reports menu is accessed:

Right-click the ruleset graphic symbol and choose ObjectReports.

11.11 Defining Rules for a Ruleset

The set of rules that make up a ruleset contain rules that usually deal with one business rule in the application. Design considerations can override this recommendation.

11-16

Analysis Stage: Building a Rule Model Types of Rules

When a ruleset is triggered, the rules in the ruleset are checked to determine if they are relevant to the situation and, if relevant, they are executed. The information you define about each rule includes the following:

The name of the rule The order the rule is executed within the ruleset The type of rule: computation, validation, fetch, fetchSQL, derivation, call, post, or component. Target object for a fetch or derivation rule Nested rulesets for a call rule and if needed, for a fetch rule Documentation of what the rule is intended to do

11.12 Types of Rules

The rules that make up a ruleset can be one of the following types:

Call
Invokes another ruleset. The rules in the nested ruleset have access to any data of the calling ruleset (including data created by computation rules or retrieved by fetch rules).

Component
Builds an XML document that is based on a business component. See XML Messaging and Business Components.

Computation
Allows for calculations to be executed. Results can be stored in the database or kept in memory for later use.

Derivation
Updates an occurrence of a particular data object, called the target object (i.e. another occurrence of the same data object, or of a different one). It may insert, change or delete occurrences in the target object. Only use a derivation rule as part of a consequence ruleset or an operation issue ruleset.

11-17

11

Analysis Stage: Building a Rule Model Types of Rules

Fetch

A derivation rule is only triggered for an operation that has no target. However, an immediate derivation is also triggered for an operation that has a target. When a derivation rule updates an occurrence, it causes the execution of the rules attached to the updated target object.

Retrieves field values from a particular target object and makes the data available to the ruleset. The target object is the data object where the information is stored in the database. The data object can be either another occurrence of the same data object, or of a different one. A fetch rule can also be used to invoke another ruleset (similar to the call rule see below).

the execution of the rules attached to the updated target object.

FetchSQL
Retrieves SQL data from an SQL table and makes the data available to the ruleset.

Nontyped Rule
Assign a nontyped rule for those occasions where you are not sure what type of rule is appropriate, but you know a rule is needed.

Post
Initiates an outbound XML message containing XML documents. See XML Messaging and Business Components.

Validation
Tests a specified condition. Only use a validation rule as part of a constraint, issue, or edit ruleset.

As part of a constraint or issue ruleset: If the condition fails, an error (or warning) message is produced. The error invalidates the update that caused the error condition, thereby rolling back any changes made. As part of an edit ruleset: If the condition fails, the occurrence is skipped and the processing continues to the next occurrence.

11-18

Analysis Stage: Building a Rule Model The Rule Context

11.13 The Rule Context

The rule context is a work area that contains all field values used by a rule. If a rule attempts to read or manipulate a field value that is not in the rule context, an error results. When a ruleset is triggered, before any of the rules in the ruleset are executed, a rule context is created. The rule context initially includes some global fields and a set of values that depend on the type of triggering object.

Field Values Initially Included in the Rule Context

The following field values are initially included in the rule context for the various type of triggering object. Note that the data triggering object can be an implemented concept, a constructor, or a class. In fact, underneath the implemented concept and the constructor is a class. Thus since the data triggering object is really a class in all these instances, only the class is referred to here as the data triggering object. Triggering Object Class Field Values in the Initial Work Area All the path fields to the constructor (key fields of the parent constructors in the constructor hierarchy). All field values of fields in the constructor that are referenced in the rule. All field values of fields in the constructor hierarchy that are referenced in the rule as DownTrigger fields. All field values in the operation. All parameter values requested by the program. All parameter values requested by the query.

Operation Program Query

Block in Form All field values in the block.

Global Fields
There are two types of global fields: system-defined global fields and user-defined global fields. System Defined Global Fields System-defined global fields allow rules to access general application information. For a complete list of all system-defined global fields see
11-19

11

Analysis Stage: Building a Rule Model The Rule Context

General Reference. The commonly used system-defined global fields are as follows: current-batch The current input batch number. Batch numbers are a method of tracking Business Integrity Server input. current-date The current system date in YYYYMMDD format.

current-form The number of the form currently displayed (i.e. if any form is currently displayed). current-time current-oper current-user The current system time in HHMMSS format. The number of the current operation. The number of the user who issued the operation.

current-world The number of the current users world. Worlds are part of eMerge security. returned-action The RETURNED-ACTION can be used to simulate an action from a rule. User Defined Global Fields User global fields are global fields that are defined via a computation rule. User global fields defined per user per session exist only for the particular user during the current session. User global fields defined per session exist for all users for the current session. For user-defined global field rule syntax, see the full computational rule syntax listed in General Reference. For more on computational rules see: Using a Computation Rule on page 16-1.

Adding Values to the Rule Context

In addition to the values initially placed in the rule context (triggering object fields, key path fields and global fields), other field values (not from the triggering object) may be referenced by a rule. Fields referenced in a rule that are not initially in the rule context are referred to as temporary fields (see below, "Temporary Fields" on page 11-22). As each rule in the ruleset is executed, more values (e.g. from a target object) may be needed in the rule context. Values needed by a rule must be added to the rule context. The method used to add values to the rule context is via a rule:

11-20

Analysis Stage: Building a Rule Model Fields in Rules

Call Rule When a rule references values returned by a program, these values must be added to the rule context. This is done by using a call rule to branch to the program. The referenced field values are added to the rule context of the rule and to all rules after it in the ruleset. Computation Rule To use temporary fields in a rule their values must be added to the rule context. This is done by calculating a value for the temporary field using a computation rule. The temporary fields are added to the rule context for the rule and to the rule context of all the rules after it in the ruleset. Fetch Rule To retrieve field values from a target object use a fetch rule. These field values are added to the rule context of the rule and to the rule context of all the rules after it in the ruleset.

The path and key fields (i.e. identifier) of the target object must be available in the rule context in order to access the target object.

FetchSQL Rule To retrieve SQL data from an SQL table use a fetchSQL rule. The data values are added to the rule context.
Any computation involving field values that have different lengths or types implicitly changes the value of the target field in the rule context. See "Field Values in Rule Context" on page 21-19.

11.14 Fields in Rules

You define fields via Modeler. All fields used in rules must be defined in the knowledgebase. They are specified in rules via their field names or eMerge field numbers. Fields can be classified according to the following:

standard fields temporary fields dynamic fields

Standard Fields
A standard field is a field that is explicitly specified in a rule and that exists in the database and the rule context. The values of these fields can change, but explicit references to these fields in the rules are fixed. Upon executing a rule, the value of the field is used.

11-21

11

Analysis Stage: Building a Rule Model Positioning a Rule

Temporary Fields
A temporary field is a field that exists in the context but does not exists in a class or in an operation. Upon executing a rule, the value of the temporary field is used. For more information see "Temporary Fields" on page 12-6.

Dynamic Fields
Dynamic fields allow you to write rule statements that contain field objects that reference other fieldsthus allowing the field value used by the rule to be changed dynamically. For more information see "Dynamic Fields" on page 12-10.

11.15 Positioning a Rule

The position you choose for a rule determines the order in which the rule is executed within the ruleset. Rules are executed from left to right. Each rule is assigned a rule number in ascending order according to its order of execution. To display ruleset numbers and rule numbers in a rule model, choose ViewOptionsPreferences. Select Rule from the Models field and click the Preferences button. Assign the Numbering On option from the dialog box that is displayed. When inserting rules in a rule model, you need not place the rule in an exact location. Instead, indicate a position for the rule relative to the location of its siblings.

11.16 Executing Rules in a Ruleset

The default procedure for executing rules in a ruleset is done in stages.

Execution Depending on Triggering Object Type

Triggering the ruleset triggers all of the rules in the ruleset. The rules are checked to determine if they should be executed. Not all rules in a ruleset are executed. Whether a rule is executed, depends on the type of triggering object. Options assigned to both the rule and the ruleset can be used to override the defaults, to specify whether or not the rule is executed.
11-22

Analysis Stage: Building a Rule Model Executing Rules in a Ruleset

Data Object Trigger

If the triggering object is a data object, by default, rules in the ruleset are executed if any of the following are true:

The rule is a fetch rule. The rule includes temporary fields. The rule includes the CURRENT-OPER global field. See "current-oper" on page 11-20. The rule is not a fetch rule, and at least one of the fields in the rule has a value other than its default. If one of the fields in the rule is assigned KeepDefault in the operation definition, it is as if it has a value and not a default value. The rule is a validation rule, and the operation is either insert or change. The rule is a derivation rule, and all path and key fields for the target constructor have values other than the defaults.

Operation Trigger

If the triggering object is an operation, by default, rules in the ruleset are executed if any of the following are true:

The rule is not a validation rule. The rule is a validation rule, and the operation code is insert. The rule is a validation rule, the operation code is change, and all of the fields in the rule have values other than their defaults or one of the fields is compared to the default.

Program or Query Trigger

If the triggering object is a program or query, by default, all of the rules in the ruleset are always executed.

Position in the Model

The rules are executed according to the order specified by their position in the rule model. The rules of a nested ruleset are executed at the point where they are nested.

Rulesets Attached to Another Class in the Same Composite

Rulesets attached to another class in the same composite are triggered as a result of the class being updated by a derivation rule.

11-23

11

Analysis Stage: Building a Rule Model Inserting a Rule in a Rule Model

Rulesets Attached to Another Class in Another Composite

Rulesets attached to another class in another composite are triggered as a result of the class being updated by a derivation rule.

11.17 Inserting a Rule in a Rule Model

Inserting any type of rule follows the same general procedure. The difference between rule types is the dialog box that is filled out as part of the rule insertion. 1 Select the ruleset for which you are inserting a rule (i.e. the owning ruleset). 2 Click the desired Rule button:

computation validation

fetch derivation call fetchSQL

post and component nontyped See XML Messaging

3 Choose a position for the rule. If this is the rulesets first rule, the position of the rule is determined automatically. If the ruleset already has rules, the pointer changes to , and the status line prompts you to choose a position. Click on the position among the sibling rules where you want to place the rule. The significance of the position of a rule is discussed on "Positioning a Rule" on page 11-22. Each rule inserted in a rule model is given a different sequential number. You can insert up to ninety-nine rules for each ruleset. For the first fortynine rules inserted into a ruleset, the rule numbering is managed automatically by eMerge. If there are forty-nine rules defined for a ruleset, and you want to insert another rule, you are prompted by the system to:

select the sibling rule near which you want to insert the new rule choose Object > Rule Renumbering

This indicates to eMerge to perform an automatic renumbering around the sibling rule selected, to make room for the new rule. Once renumbering is completed, you can insert the new rule.

11-24

Analysis Stage: Building a Rule Model Computation Rule

To display the numbers for rulesets and rules in the rule model, do the following: Choose View > Options > Preferences. Select Rule from the Model drop-down listbox. Click Preferences. Assign Numbering On. Click OK.

The symbol for the rule appears under the ruleset and the appropriate rule dialog box opens. See the sections below for how to fill in the dialog boxes for each rule type.

11.18 Computation Rule

When you insert a computation rule, the symbol for the rule appears under the ruleset and the Computation Rule dialog box opens:

1 Enter the name of the rule in the Name textbox. The name can be up to 32 characters, consisting of letters, digits, blanks and any of: - _ ' " . ( ) and #. The first character must be a letter. 2 Click OK. On completion, the rule name appears on the symbol in the model.

11.19 Validation Rule

When you insert a validation rule, the symbol for the rule appears under the ruleset and the Validation Rule dialog box opens:

11-25

11

Analysis Stage: Building a Rule Model Fetch Rule

1 Enter the name of the rule in the Name textbox. The name can be up to 32 characters, consisting of letters, digits, blanks and any of: - _ ' " . ( ) and #. The first character must be a letter. 2 Click OK. The rule name appears on the symbol in the model.

11.20 Fetch Rule

When you insert a fetch rule, the symbol for the rule appears under the ruleset and the Fetch Rule dialog box opens:

11-26

Analysis Stage: Building a Rule Model Fetch Rule

Filling in the Fetch Rule Dialog Box

1 Enter the name of the rule in the Name textbox. The name can be up to 32 characters, consisting of letters, digits, blanks and any of: - _ ' " . ( ) and #. The first character must be a letter. 2 Enter the type of target object from which you want to fetch (i.e. retrieve any field values and make the data available to the ruleset) in the Target groupbox in the Type drop-down listbox. 3 Enter the name of the target object in the Target groupbox in the Name textbox. Click the Find button to see the names of existing concepts or constructors, depending on which type of target object you chose. If the target type is a concept in design or implementation stage, and if you do not define a design number, the number of the main design is entered automatically. If the target concept is in analysis stage, there is no design number. When the object is advanced to design or implementation, the number of the main design is entered automatically. The number of a constructor or a class in a composite is entered automatically.

You may define the target object later. See "Defining a Target Object after Inserting the Derivation Rule" on page 11-32 for how to define the target object at a later stage.

4 Enter the name of the nested ruleset that is called when the fetch is successful in the Then textbox in the Rulesets groupbox. If the ruleset is new (i.e. has not as yet been defined), click the New checkbox. If the ruleset is not new (i.e. it has already been defined), click the Find button to see the names of existing rulesets. 5 If there is a ruleset that is called if the fetch is unsuccessful, enter the name of the ruleset that is called in the Else textbox in the Rulesets groupbox. If the ruleset is new (i.e. has not as yet been defined), click the New checkbox. 6 Click OK.

Resulting Model Symbols

On completion, the rule name appears on the symbol in the model. The target concept symbol and nested rulesets (if there are any) appear with
11-27

11

Analysis Stage: Building a Rule Model Fetch Rule

an arrow pointing toward the rule. Then and Else appear above the relevant nested ruleset symbol. Example: rulesets A fetch rule with a target object and then and else nested

If you have not entered the name of the target object, the rule appears with an empty target symbol (i.e. an empty rectangle) with an arrow pointing toward the rule.

Defining a Target Object after Inserting the Fetch Rule

You can define a target object after inserting the fetch rule: 1 Double-click the empty target object symbol (i.e. attached to the fetch rule object). Or Select the empty target object symbol and choose ObjectProperties.

11-28

Analysis Stage: Building a Rule Model FetchSQL Rule

The Target dialog box opens:

2 Enter the type of target object from which you want to fetch (i.e. retrieve any field values and make the data available to the ruleset) in the Type drop-down listbox. 3 Enter the name of the target object in the Name textbox. Click the Find button to see the names of existing data objects, depending on which type of target object you chose. If the target type is a concept in design or implementation stage, and if you do not define a design number, the number of the main design is entered automatically. If the target concept is in analysis stage, there is no design number. When the object is advanced to design or implementation, the number of the main design is entered automatically. The number of a constructor or a class in a composite is entered automatically. 4 Click the OK button.

11.21 FetchSQL Rule

When you insert a fetchSQL rule, the symbol for the rule appears under the ruleset and the SQL Fetch Rule dialog box opens:

11-29

11

Analysis Stage: Building a Rule Model Derivation Rule

1 Enter the name of the rule in the Name textbox. The name can be up to 32 characters, consisting of letters, digits, blanks and any of: - _ ' " . ( ) and #. The first character must be a letter. 2 Enter the name of the nested ruleset that is called when the fetchSQL is successful in the Then textbox in the Rulesets groupbox. If the ruleset is new (i.e. has not as yet been defined), click the New checkbox. If the ruleset is not new (i.e. it has already been defined), click the Find button to see the names of existing rulesets. If there is a ruleset that is called if the fetchSQL is unsuccessful, enter the name of the ruleset that is called in the Else textbox in the Rulesets groupbox. If the ruleset is new, click the New checkbox. If the ruleset is not new, click the Find button to see the names of existing rulesets. 3 Click OK. On completion, the rule name appears on the symbol in the model. The nested rulesets (if there are any) appear with an arrow pointing toward the rule. Then and Else appear above the relevant nested ruleset symbol.

11.22 Derivation Rule

When you insert a derivation rule, the symbol for the rule appears under the ruleset and the Derivation Rule dialog box opens:
11-30

Analysis Stage: Building a Rule Model Derivation Rule

Filling in the Derivation Rule Dialog Box

1 Enter the name of the rule in the Name textbox. The name can be up to 32 characters, consisting of letters, digits, blanks and any of: - _ ' " . ( ) and #. The first character must be a letter. 2 Enter the type of target object to which you want to write (i.e. insert, change, or delete occurrences) in the Type drop-down listbox in the Target groupbox. 3 Enter the name of the target object in the Target groupbox in the Name textbox. When a derivation rule updates an occurrence, it causes the execution of the rules attached to the updated target object. Click the Find button to see the names of existing data objects, depending on which type of target object you chose. If the target type is a concept in design or implementation stage, and if you do not define a design number, the number of the main design is entered automatically. If the target concept is in analysis stage, there is no design number. When the object is advanced to design or implementation, the number of the main design is entered automatically. The number of a constructor or a class in a composite is entered automatically.

You may define the target object later. See "Defining a Target Object after Inserting the Derivation Rule" below for how to define the target object at a later stage.

4 Click OK.

11-31

11

Analysis Stage: Building a Rule Model Derivation Rule

Resulting Model Symbols

On completion, the rule name appears on the symbol in the model. The target concept symbol appears with an arrow pointing away from the rule.

If you have not entered the name of the target object, the rule appears with an empty target symbol (i.e. an empty rectangle) with an arrow pointing away from the rule.

Defining a Target Object after Inserting the Derivation Rule

You can define a target object after inserting the derivation rule: 1 Double-click the empty target object symbol (i.e. attached to the derivation rule object). Or Select the empty target object symbol and choose Object Properties.

11-32

Analysis Stage: Building a Rule Model Call Rule

The Target dialog box opens:

2 Enter the type of target object to which you want to write (i.e. insert, change, or delete occurrences) in the Type drop-down listbox. 3 Enter the name of the target object in the Name textbox. Click the Find button to see the names of existing data objects, depending on which type of target object you chose. If the target type is a concept in design or implementation stage, and if you do not define a design number, the number of the main design is entered automatically. If the target concept is in analysis stage, there is no design number. When the object is advanced to design or implementation, the number of the main design is entered automatically. The number of a constructor or a class in a composite is entered automatically. 4 Click the OK button.

11.23 Call Rule

When you insert a call rule, the symbol for the rule appears under the ruleset and the Call Rule dialog box opens:

11-33

11

Analysis Stage: Building a Rule Model Call Rule

Filling in the Call Rule Dialog Box

1 Enter the name of the rule in the Name textbox. The name can be up to 32 characters, consisting of letters, digits, blanks and any of: - _ ' " . ( ) and #. The first character must be a letter.` 2 If the call rule is not conditional, enter the name of the ruleset that is called in the Then textbox in the Nested Rulesets groupbox. If the nested ruleset is new (i.e. has not as yet been defined), click the New checkbox next to the Then textbox. If the call rule is conditional, enter the name of the ruleset that is called if the condition is met in the Then textbox, and the name of the ruleset that is called if the condition is not met in the Else textbox. If either nested ruleset is new, click the New checkbox next to the respective textbox. If the nested ruleset is not new (i.e. it has already been defined), click the Find button to see the names of existing rulesets. 3 Click OK.

11-34

Analysis Stage: Building a Rule Model Call Rule

Resulting Model Symbols

On completion, the rule name appears on the symbol in the model. Then and Else appear above the relevant nested ruleset symbol.

If you have not entered the name of the nested ruleset, the rule appears with an empty ruleset symbol (i.e. an empty rectangle) with the word Then above the nested ruleset symbol.

Defining a Nested Ruleset after Inserting the Call Rule

You can define a nested ruleset after inserting the call rule: 1 Double-click the empty nested ruleset symbol (i.e. attached to the call rule object). Or Select the empty nested ruleset symbol and choose ObjectProperties.

11-35

11

Analysis Stage: Building a Rule Model Component Rule

The Ruleset dialog box opens:

2 Enter the name of the nested ruleset in the Name textbox. If the nested ruleset is not new (i.e. it has already been defined), click the Find button to see the names of existing rulesets.

11.24 Component Rule

When you insert a derivation rule, the symbol for the rule appears under the ruleset and the Component Rule dialog box opens:

Filling in the Component Rule Dialog Box

1 Enter the name of the rule in the Name textbox.

11-36

Analysis Stage: Building a Rule Model Post Rule

The name can be up to 32 characters, consisting of letters, digits, blanks and any of: - _ ' " . ( ) and #. The first character must be a letter.` 2 If the component rule is not conditional, enter the name of the ruleset that is called in the Then textbox in the Nested Rulesets groupbox. If the nested ruleset is new (i.e. has not as yet been defined), click the New checkbox next to the Then textbox. If the component rule is conditional, enter the name of the ruleset that is called if the condition is met in the Then textbox, and the name of the ruleset that is called if the condition is not met in the Else textbox. If either nested ruleset is new, click the New checkbox next to the respective textbox. If the nested ruleset is not new (i.e. it has already been defined), click the Find button to see the names of existing rulesets. 3 Click OK.

11.25 Post Rule

When you insert a derivation rule, the symbol for the rule appears under the ruleset and the Post Rule dialog box opens:

Filling in the Post Rule Dialog Box

1 Enter the name of the rule in the Name textbox. The name can be up to 32 characters, consisting of letters, digits, blanks and any of: - _ ' " . ( ) and #. The first character must be a letter. 2 Click OK

11-37

11

Analysis Stage: Building a Rule Model Nontyped Rule

11.26 Nontyped Rule

When you insert a nontyped rule, the symbol for the rule appears under the ruleset and the Nontyped Rule dialog box opens:

Filling in the Nontyped Rule Dialog Box

1 Enter the name of the rule in the Name textbox. The name can be up to 32 characters, consisting of letters, digits, blanks and any of: - _ ' " . ( ) and #. The first character must be a letter. 2 Click OK.

Resulting Model Symbols

On completion, the rule name appears on the symbol in the model.

A nontyped rule cannot advance to the design or implementation stage. You must assign a type to the rule before it is possible.

Assigning the Type of a Nontyped Rule

You can assign the type of a nontyped rule: 1 Select the rule whose type you want to assign. 2 Choose Edit Assign Type. The Assign Type submenu shows the five types of rules.

11-38

Analysis Stage: Building a Rule Model Copying a Rule

3 Click the type you want. The dialog box appropriate to the rule type is displayed. 4 Fill in the dialog box and click OK. See the procedures above for filling in the dialog box for each rule type.

11.27 Copying a Rule

A rule can be reused within a ruleset, or it can be reused in other rulesets in the model, by copying the rule text for the rule.

Copying a Rule Within the Same Ruleset

1 From the rule model, select the particular rule (via its symbol) to be copied. 2 Choose Edit Copy Special.

11-39

11

Analysis Stage: Building a Rule Model Documenting a Rule

3 Select the ruleset to which the rule is to be copied. Locate and click the pointer in the rule model. The rule dialog box for the particular type of rule being copied is displayed:

4 Fill in the Name textbox and click OK. The copied rule appears in the model with the assigned name listed in the copied rule symbol:

The rule text for the Copied Date rule is copied, within the same ruleset, from the New Date rule.

11.28 Documenting a Rule

During analysis, besides defining each rule, you should document what the rule is intended to do.

To document a rule:

1 Click the rule that you want to document.

11-40

Analysis Stage: Building a Rule Model Documenting a Rule

2 Choose Object Documentation. The Rule Documentation (200009) form is displayed with the name of the ruleset displayed in the Ruleset field and the name of the rule displayed in the Rule field.

3 Enter the documentation text in the Documentation groupbox. 4 When you are finished, click the OK button to return to the rule model.

11-41

11

Analysis Stage: Building a Rule Model Documenting a Rule

11-42

Chapter 12 Design Stage: Composing Rules

When a rule is in the design stage, the default symbol for the rule is yellow with no pattern. For a description of the analysis stage, see Chapter 11, Analysis Stage: Building a Rule Model. In analysis, the rule symbol in the rule model is blue. During design: rules are composed by writing the rule text within an eMerge rule appropriate options are assigned to the rule error messages are entered (if needed) Rule Editor, an interactive Development Workbench tool, is availbale to the developer, to help compose the rules (see Chapter 13, Rule Editor).

12.1 Advancing a Rule to Design

The design stage begins for any rule as soon as you access the rule definition form and begin to enter some rule text, assign rule options, or enter an error message (for a validation or fetch rule). The color and pattern of the rule symbol reflect the change to the design stage (blue to yellow) even if you do not finish the rule specification. The design stage is in effect as soon as you click Apply or OK on the appropriate rule definition form.

Accessing the Rule Definition Forms

Use a rule definition form and its related forms to specify the rule definition. 1 Double-click the rule symbol for which you want the rule definition form. Or Select the rule symbol for which you want the rule definition form, and click the Rule button or choose Object Rule Definition. The appropriate rule definition form open for the rule type:
12-1

12

Design Stage: Composing Rules Advancing a Rule to Design

Computation Rule

Validation Rule

Fetch Rule FetchSQL Rule Derivation Rule

Call Rule

Example Rule Definition Form

The rule definition form has the following information filled in:

ruleset number and name rule number and name

12-2

Design Stage: Composing Rules Advancing a Rule to Design

The following is a typical rule definition form for a computation rule, showing the ruleset number and name, the rule number and name, and the rule statements:

If you want to modify any of the above, it must be done in the rule model. See Chapter 13, Rule Editor. When you finish, you can either return to the rule model or compile the rule. The following chapters describe the specific rule types, their definition forms, the rule syntax for each rule type, and some examples using each specific rule type. For a description of the forms and the syntax for the different rules, refer to the General Reference.

12-3

12

Design Stage: Composing Rules Using Synonyms to Reference Knowledgebase Objects

Writing the Rule Text

The following apply to the rule text for any rule type:

The rule text can be written in upper or lowercase letters or a combination of upper and lower. Any space or special character within a field name mentioned in the rule text is replaced by a dash (-). Trailing special characters are deleted. Multiple dashes are replaced by a single dash. A rule statement can extend over several lines (use <Shift>+<Enter> to obtain a new line). Each rule consists of only one statement which must end with a period.

12.2 Using Synonyms to Reference Knowledgebase Objects

Rule statements contain references to objects (fields or classes) in the knowledgebase. Objects can be referenced by their name and/or their number. The name can be replaced by a synonym. A synonym is given automatically to an object upon object definition unless the NoAutoSynonyms option has been defined for the database. The automatically defined synonym consists of a letter (alpha character) specific to the object type, concatenated with the unique object number: F S field (For example, F3000.) class (For example, S33.)

You can also reference an object via a user defined synonym. For information on how to define your own synonyms, see "Using Synonyms" on page 5-5.

12.3 Making a Rule Conditional

A validation, computation, derivation, fetch, fetchSQL or call rule can be made conditional. Use conditionality if the actual rule is dependent on certain information.

12-4

Design Stage: Composing Rules Making a Rule Conditional

Syntax
The syntax for the condition is the same for the five types of rules.

IF <field> <expression>

Introduces a conditional rule. The name of a field in the work area. A numeric or character expression comprising values (numbers, character strings or dates), fields and operators (+-*/):

A field can be from the triggering object, from a computed field from another rule, or from a global field (e.g. CURRENT-OPER). (See page 11-1 for information about global fields.) If no relationship is specified (EQ, NE etc.), EQ is assumed. <rule> The rule syntax for a validation, computation, derivation or call rule. The rule syntax does not include the period. The rule type used in the THEN clause must be the same as the rule type used in the ELSE clause (if an ELSE clause is used).

Example
if credit-rating lt 10 then total-price must be le 20000.

12-5

12

Design Stage: Composing Rules Fields in Rules

12.4 Fields in Rules

Rule text consists of a collection of keywords, logical conditions, and fields complying with rule syntax conventions. In addition to standard fields, the rule text can contain temporary fields and/or dynamic fields.

12.5 Temporary Fields

Temporary fields allow you to write rule statements that reference field objects that exist only in the rule context. A temporary field is a field that exists in the context but does not exists in a class or in an operation. Upon executing a rule, the value of the temporary field is used. Define the field as a field in a concept with the NotInClass, NotInOperation options assigned to the field. From the rule definition form, you can obtain a list of existing temporary/global fields defined in the knowledgebase or define a new field. This feature facilitates composing the rule text. You can limit the search for temporary field information by specifying filtering criteria.

12-6

Design Stage: Composing Rules Temporary Fields

Listing Temporary Fields

To list temporary/global fields:

1 From the rule definition form, click the TempFields button. The Temporary/Global Fields form is displayed:

2 Enter any filtering criteria you require in the Filtering textboxes. If no filtering criteria are supplied, all temporary/global fields in the knowledgebase are listed.

12-7

12

Design Stage: Composing Rules Temporary Fields

3 Click the FieldList button. A list of temporary/global fields filtered to your requirements is presented:

Note: There are temporary fields defined in the knowledgebase that are not in the rule context. The type of temporary field (i.e. in the rule context or not in the rule context) is indicated by displaying alongside the temporary field an icon specific to the temporary field type. (The legend at the bottom of the form shows the icons for temporary fields in the knowledgebase. The icon with the exclamation symbol (!) indicates a temporary field that is in the rule context.)

Defining a New Temporary Field in the Knowledgebase

You can define a new field in the knowledgebase that can be used as a temporary field. 1 From the rule definition form, click the TempFields button. The Temporary/Global Fields (20439) form is displayed.

12-8

Design Stage: Composing Rules Temporary Fields

2 Click the New button. The Concept New Temporary Field (2017) form is displayed:

A different field definition form is displayed depending on the triggering object (or no triggering object). For example, Field Definition (100104) form is displayed if there is no triggering object.

3 Enter a name for the temporary field in the Field textbox. You can enter a data type and size for the fields in the Data Type and Size textboxes (optional). 4 Click Apply. The NotInClass and NotInOperation options are automatically assigned to the fields.

12-9

12

Design Stage: Composing Rules Dynamic Fields

5 You can view definitions for the temporary field and assign options to the temporary field via the Field Definition form. Click the FieldDef button to access the Field Definition (2108) form:

6 Assign options to the fields you require. 7 Click OK to save information and return to the Concept: New Temporary Field form. 8 Click OK. The field is now defined in the knowledgebase. It is not associated with any operation or class.

12.6 Dynamic Fields

Dynamic fields allow you to write rule statements that contain field objects that reference other fieldsthus allowing the field value used by the rule to be changed dynamically. By using a dynamic field in a rule statement you instruct the rule to use the value of the field that is pointed to by the field you specify in the dynamic field clause. You specify a dynamic field in a rule by preceding the field name and/or number with an at symbol (@).

12-10

Design Stage: Composing Rules Dynamic Fields

This indicates to eMerge that the value of the field preceded by the ampersand is not a data value to be used when executing the rule but is the number of another eMerge field whose value you want to use when executing the rule. You can use other rules to dynamically change the value of the dynamic field (the one preceded by the ampersand) thereby giving the rule dynamic access to any eMerge field value. All fields referenced by a dynamic field must be in the rule context.

If you are uncertain if a field (e.g. Field3, #30000) that is referenced by a dynamic field is in the rule context, use a rule statement such as: Field3 must be eq to Field3., to put the field in the rule context.

Example: @Field1 is targetkey for Field2. The value of Field1 is 30000. The value of field #30000 is used when the rule is executed.

12-11

12

Design Stage: Composing Rules Dynamic Fields

12-12

Chapter 13 Rule Editor

Rule Editor is an interactive Development Workbench tool that helps the developer compose rules. Rule Editor is accessed from the rule model of Modeler. When Rule Editor is enabled, the Rule Text groupbox of the rule definition forms displays rule keywords, data objects, values, comments and errors in different colors for easy identification, and can prompt for keywords, data objects and functions. Rule Editor helps the rule developer with the following:

prompting for rule keywords and data objects writing rule statements having correct syntax editing text easily

13-1

13

Rule Editor Rule Text Categories

Rule Editor is supported by rule definition forms used to specify the various types of rules (computation, validation, derivation, fetch, fetchSQL, post, component, and call rules).

major keywords

field

value

minor keywords

You can disable the Rule Editor by issuing the RULEEDITOR OFF command.

13.1 Rule Text Categories

A rule statement (after being checked for syntax errors) can contain the following text categories, displayed in different colors or fonts. See "Changing Formatting for Display of Rule Text" on page 13-11 Major keywords These keywords usually begin or define a clause in the rule statement.

if else then

13-2

Rule Editor Prompting for Keywords and Data Objects

use when where while post component call

Minor keywords Data objects Values Comments Errors Text

Keywords that do not begin a clause. All other keywords not listed as a major keyword. Constructors, classes, composites, fields, etc. Strings within quotation marks (e.g. dddnnn). Numeric data. Rule text statements beginning with /* (slash asterisk). Syntax errors. Any rule text displayed before being classified by Rule Editor.

13.2 Prompting for Keywords and Data Objects

Rule Editor assists the developer by prompting for keywords and data objects as required in the rule statement. When prompting, Rule Editor displays a list of possible keywords and a list of possible data objects. The following types of prompting are provided:

Auto Prompt Prompt Now

You can return to the beginning of a prompt list by choosing Return (from the prompt list). If nested prompt lists were displayed, Return accesses the previous (last) prompt list displayed.

Auto Prompt
Rule Editor can be set for automatic prompting. When using Auto Prompt, Rule Editor automatically displays, before each word, a list of major/minor keywords and a list of data objects that are valid for the current pointer location in the rule statement.

13-3

13

Rule Editor Prompter Options

To assign Auto Prompt:

1 Right-click the rule text window of the rule definition form. A menu is displayed.

2 Choose Auto Prompt. A check appears on the menu indicating that Auto Prompt is assigned. Unassign Auto Prompt by clicking the Auto Prompt again (toggling).

Prompt Now
Rule Editor can be set for immediate prompting for required information at the current pointer location by choosing the Prompt Now option. Rule Editor prompts for information that is required at the start of the current word location irrespective of where the pointer is located in the currently entered word. If there is a syntax error in the rule statement prior to the pointer location at which Prompt Now is invoked, an error is generated and no prompt information is displayed.

To invoke immediate prompting:

1 Right-click the rule text window. 2 Choose Prompt Now from the menu that is displayed. <Ctrl>+<Q> can be used instead of choosing Prompt Now.

13.3 Prompter Options

Prompter options allow you to manipulate and filter the information displayed for a prompt.

13-4

Rule Editor Prompter Options

Choosing Prompter Options

1 Right-click the rule text window of the rule definition form. A menu is displayed. 2 Choose Options > Prompter. The following pop-up menu is displayed:

3 Choose the prompt options you require.

Prompter Options
Display FieldIdentifiers Displays the identifiers (i.e. field names) of fields:

13-5

13

Rule Editor Prompter Options

Display FieldIdentifiers and Numbers

Displays the identifiers and numbers of fields:

Display FieldIdentifiers and Class-Name

Displays the identifiers and class names of fields:

Sort by Name

Sorts the displayed information alphabetically by name:

13-6

Rule Editor Prompter Options

Sort by Type

Sorts the displayed information by object type:

Filter Item

Forces the prompt to display information that best matches the text string near the current pointer location. If Filter Item is assigned and a Prompt Now request is made and no information matching the filtered request is found, then no prompt response is given. If the Filter Item option is not assigned, all possible field names are displayed with the first closest match to the string Field highlighted. Example: While composing a rule, a Prompt Now is needed to obtain information on a field name. The following incomplete rule statement is entered (a vertical line (|) indicates the pointer location):
If Fieldb = Sales then Field|

Requesting a Prompt Now with the Field-Name prompt option selected and the pointer positioned at the end of the string Field (i.e. at the vertical line) prompts for information on possible field names. If the Filter Item option is assigned, only field names having the string Field somewhere in the field name are displayed.

If no items matching the string Field are found, no prompt response is given.

13-7

13

Rule Editor Prompting for Functions

Keyword Filter

Displays a list of all keywords and symbols used in all rules. You can choose the keywords and symbols you want displayed when using the prompter by selecting the checkbox for the keyword or symbol.

Click Default Settings to return to the initial keyword and symbol choice selections.

13.4 Prompting for Functions

eMerge provides for the use of functions in business rules. When Rule Editor prompting is invoked, Rule Editor indicates where a function can be used in the rule statement by listing the object type Functions in the displayed prompt list.

13-8

Rule Editor Prompting for Functions

When you select Functions from the prompt list, function categories are displayed:

Select a function category (e.g. String), to display a list of available functions for the chosen function category:

Once you select a function, Rule Editor prompts for function parameters as required. For more information on the use of functions in business rules see Chapter 24, Using Built-In Functions in Rules.

Return accesses the previous prompt list displayed.

13-9

13

Rule Editor Checking Rule Syntax

13.5 Checking Rule Syntax

You can check a rule statement for syntax errors without compiling the rule. All the rule statements appearing in the rule text window are checked. 1 Right-click the rule text window of the rule definition form. A menu is displayed:

2 Choose Check Syntax. The rule statements are checked immediately for syntax errors. Erroneous text is displayed in the color and style defined for an error. See "Changing Font Style, Color or Underline for a Text Category" on page 13-11.

Use <Ctrl>+<R> for syntax checking instead of choosing Check Syntax.

13.6 Editing Rule Text

You can copy, cut, and paste rule text. In addition, Rule Editor has an unlimited undo and redo capability. Right-click the rule text window of the rule definition form and choose the required editing option:

13-10

Rule Editor Changing Formatting for Display of Rule Text

13.7 Changing Formatting for Display of Rule Text

You can change the display definitions for text categories appearing in a rule statement:

font style font color word underline word case

Changing Font Style, Color or Underline for a Text Category

Formatting of rule text display is done by category. Check the rule text display definitions and change them to your requirements: 1 Right-click the rule text window of the rule definition form. A menu is displayed:

2 Choose Options > Format. The Format dialog box is displayed:

13-11

13

Rule Editor Changing Formatting for Display of Rule Text

3 Select a text category from the Category listbox. 4 Format the text category:

Select the display color from the Color drop-down box Select the display font style from the Font Style listbox Assign Underline if required

The Sample box displays a preview of the formatting selected. 5 Click OK

Click Restore Default Settings to reset formatting to initial settings.

Selecting the Display Case for Rule Text

1 Right-click the rule text window of the rule definition form. A menu is displayed. 2 Choose Options > Change Case. The Change Case dialog box is displayed:

3 Choose the case:

All characters upper case. All characters lower case. First character upper case, remaining characters lower case (for data objects only).

For data objects, the Initial default case is Title Case. Once changed, the selected option becomes the default (until changed again).

4 Click OK.

13-12

Chapter 14 Implementation Stage of a Rule

This chapter describes the implementation stage of a rulethe third of the three Modeler development stages: analysis, design and implementation. When a rule is in the implementation stage, the supplied default for the rule symbol is green with no pattern. For a description of the analysis stage, see Chapter 11, Analysis Stage: Building a Rule Model. For a description of the design stage, see Chapter 12, Design Stage: Composing Rules. On implementation of a rule, Modeler takes the rule specification and generates the necessary cross references between the structures and compiles the rule. After all the rules of a ruleset are compiled (i.e. implemented), test the ruleset by testing the triggering object. For example, if the rulesets triggering object is a concept, access the implemented concept to test it with its rules.

14.1 Requirements for Implementing a Rule

The following table shows what is required, optional and not applicable (n.a.) for each rule type before a rule can be implemented (i.e. compiled), and whether the requirement is defined via the rule model or the rule definition form:

Requirements Defined via the Rule Model

Requirement Computation Validation ruleset name rule name target object required required n.a. required required n.a. n.a. Fetch Derivation Call required required n.a. required

required required required required required required optional n.a.

nested ruleset n.a.

14-1

14

Implementation Stage of a Rule Implementing a Rule

Requirements Defined via the Rule Definition Form

In some circumstances the options are required. See the General Reference for more information. Requirement Computation Validation options rules target object rule text optional n.a. required optional n.a. required required optional optional required required optional n.a. required required optional n.a. n.a. required Fetch Derivation Call

error message n.a.

14.2 Implementing a Rule

You must compile a rule whenever you make any changes to the rule text. If you change the information describing the rule (e.g. the error message), or change any of the rule options (including target options for fetch and derivation rules), you do not need to recompile the rule. After the rule is compiled the color and pattern of the graphic symbol for the rule changes to the color and pattern that indicate the implementation stage. Modeler sends a request to Business Integrity Server, and the appropriate modifications are made to the knowledgebase.

Implementing (Compiling) a Rule from the Rule Model

1 Select the rule. 2 Click the Implementation button or choose ObjectImplementation.

Implementing (Compiling) a Rule from the Rule Definition Form

Click the Compile button. If you made any errors (syntax or logic errors), an error message is displayed either during compilation (syntax errors) or execution (logic errors) of the rule in the ruleset.

14-2

Chapter 15 Working with the Rule Model

15.1 Viewing Details of Objects

You can view the details of objects and of the connections between objects within the rule model. Some details can be modified as well as viewed, while others can only be viewed. The details are viewed via a dialog box.

Displaying an Object or Connection Detail Dialog Box

1 Double-click the object (or the connection, i.e. the line between two objects). The relevant dialog box opens. 2 Modify the information in the dialog box, if you want, and click OK. Or If there is nothing that you want to modify, click Cancel.

Available Detail Dialog Boxes

These detail dialog boxes allow viewing and/or modifying: Dialog Boxes for Rules These detail dialog boxes allow you to view and modify rules.

call rule component rule computation rule derivation rule fetch rule fetchSQL rule post rule validation rule non-typed rule

15-1

15

Working with the Rule Model Changing the Execution Order of Rulesets and Rules

Dialog Boxes for Rulesets Dialog Boxes for Connections

This detail dialog box allows you to view and modify rulesets.

root ruleset, ruleset attached to a triggering object, nested ruleset

These detail dialog boxes allow you to view and modify connections.

between a triggering object and a ruleset between a rule and a target concept between a rule and a target class in composite between a rule and a target constructor between a rule and a nested ruleset

View Only Dialog Boxes

Objects that are created outside the rule model cannot be modified within the rule model. These detail dialog boxes only allow viewing:

triggering concept triggering design of a concept triggering constructor triggering class in composite triggering operation defined via a constructor triggering operation defined directly target concept target constructor target class in composite

15.2 Changing the Execution Order of Rulesets and Rules

The position choosen for a ruleset determines the order in which the ruleset is triggered for its triggering object. In addition, constraint rulesets must be located to the left of all consequence rulesets, and issue rulesets must be located to the left of all edit rulesets. Thus, for example, if you place a ruleset to the left of a constraint ruleset, the ruleset must be a constraint. If you place a ruleset to the right of a consequence ruleset, the ruleset must be a consequence. Similarly, the position you choose for a rule determines the order in which the rule is executed within the ruleset. Rules are executed from the left to the right. (See Positioning a Rule on page 11-22). Thus, moving a ruleset or rule, relative to its siblings, in a rule model, changes the execution order of the rulesets or rules. You are restricted where you can place a ruleset or rule. You can decide on its position relative to its siblings, but the exact location is chosen automatically based on your choice of relative position.

15-2

Working with the Rule Model Copying a Ruleset or a Rule

To move a ruleset or rule among its siblings; change the execution order:

1 Select the ruleset or rule that you want to move. 2 Drag the ruleset or rule to its new position among its siblings. For more details on positioning rulesets in the rule model see: Ruleset Triggering Order Within a Model on page 11-3.

15.3 Copying a Ruleset or a Rule

A ruleset can be reused in the same model. In addition, a rule can be copied from one ruleset to another ruleset.

Copying a Ruleset
A ruleset can be used more than once in the same rule model. For example, the same ruleset can be attached to more than one call rule. Only one definition of each ruleset is kept in the knowledgebase. Any changes you make to one copy is reflected in all copies. 1 Right-click the ruleset and choose Attach from the popup menu. Or Select the ruleset and choose EditAttach. 2 Click the new triggering object or calling rule. The system response depends on the type of object or rule. For a Triggering Object The system response depends on whether or not this is the objects first dependent.

If this is the triggering objects first dependent, its position is determined automatically. If the triggering object already has dependents, the status line prompts you to choose a position. Click the position among the siblings where you want to place this copy of the ruleset.

For a Calling Rule

The system response depends on whether the calling rule is a fetch rule or a call rule.

If the calling rule is a fetch rule, the newly attached ruleset is a THEN ruleset.
You can change the THEN ruleset to an ELSE ruleset via the ruleset dialog box. Double-click the newly attached THEN ruleset and in the ruleset dialog box that is displayed choose Else.
15-3

15

Working with the Rule Model Copying a Ruleset or a Rule

If the calling rule is a call rule, the newly attached ruleset is an ELSE ruleseteven if you have not as yet attached a THEN ruleset to the call rule.

The symbols for a copied ruleset and its rules (both original and copy) have a small red circle displayed, indicating that the ruleset is being reused in the model:

Copying a Rule
A rule can be copied and attached as a new rule to the same ruleset. When copying a rule, define a new name to the copy of the rule. If there is a target object and nested rulesets attached to the rule, they are also copied.

To copy a rule:

1 From the rule model, select the particular rule (via its symbol) to be copied. 2 Choose Edit Copy Special.

15-4

Working with the Rule Model Copying a Ruleset or a Rule

3 Select the ruleset to which the rule is to be copied. Locate and click the pointer in the rule model. The appropriate rule dialog box for the particular type of rule being copied is displayed:

4 Fill in the Name textbox and click OK. The copied rule appears in the model with the specified name listed in the copied rule symbol:

Example: The rule text for the Copied Day Of Week rule in ruleset2 is copied from the Calculate Day Of Week rule of ruleset1.

15-5

15

Working with the Rule Model Deactivating a Ruleset or Rule

15.4 Deactivating a Ruleset or Rule

Deactivating a Ruleset
A ruleset can be made inactive so that it is not executed. The ruleset is not deleted, but is skipped over at execution. 1 Double-click the ruleset that you want to inactivate. The Ruleset dialog box is displayed:

2 Unassign Active.

Deactivating a Rule
A rule can be made inactive so that it is not executed. The rule is not deleted, but is skipped over during execution.

15-6

Working with the Rule Model Deleting a Ruleset or Rule

1 Double-click the rule that you want to inactivate. The rule dialog box is
displayed:

During testing, a rule can be inactivated to simplify the testing by excluding the rule.

2 Unassign Active.

15.5 Deleting a Ruleset or Rule

Deleting a Ruleset
Deleting a ruleset removes it from the model and from the knowledgebase. Deleting a ruleset deletes all the rules in the ruleset. A ruleset cannot be deleted if it is used more than once in the model or in more than one model. If a particular ruleset is used more than once in a model, Delete is not available for that ruleset. To delete a ruleset that is being used in more than one model, exclude the ruleset from all other models in which it is being used before deleting it.

To delete a ruleset within a rule model: Right-click the ruleset and choose Delete from the popup menu that is displayed. Or Select the ruleset to delete and choose EditDelete.

Deleting a Rule
Deleting a rule removes it from the model and from the knowledgebase.

15-7

15

Working with the Rule Model Listing Ruleset Triggering Objects

To delete a rule: Right-click the rule to delete and choose Delete from the popup menu that is displayed. Or Select the rule to delete and choose EditDelete.

15.6 Listing Ruleset Triggering Objects

To produce a report that lists all the objects that trigger the ruleset: Right-click the ruleset and choose ObjectReports from the popup menu that is displayed. Or Select the ruleset and choose ObjectReports.

15.7 Detaching a Ruleset or Target Object

Detaching a ruleset breaks the connection between it and its triggering object. The ruleset symbol remains on the rule model (unattached to a triggering object) for the current rule model session. Detaching a target object breaks the connection between it and its calling rule. (For comparison, see "Fully Detaching a Ruleset or Target Object" on page 15-9.)

A rule cannot be detached.

To detach a ruleset: Right-click the ruleset or target object and choose Detach from the popup menu that is displayed. Or Select the ruleset or target object that you wish to detach and choose EditDetach. The system response depends on whether the detached object is a ruleset or a target object.

For a Ruleset

If the ruleset is the only occurrence of this ruleset in the model, it remains in the model as a secondary root. If there are other occurrences of this same ruleset in the model, the selected occurrence disappears and the other occurrences remain in place. In this case, the ruleset does not remain as a secondary root.

15-8

Working with the Rule Model Fully Detaching a Ruleset or Target Object

For a Target Object

If the target object is the only occurrence of this target object in the model, the selected occurrence disappears. If there are other occurrences of this same target object in the model, the selected occurrence disappears and the other occurrences remain in place.

15.8 Fully Detaching a Ruleset or Target Object

Fully detaching a ruleset or target object breaks the connection between it and its triggering object or calling rule, respectively, in every place that it occurs in the current model. (For comparison see "Detaching a Ruleset or Target Object" on page 15-8.)

A rule cannot be fully detached.

To fully detach a ruleset: Right-click the ruleset or target object and choose Detach Fully from the popup menu that is displayed. Or Select the ruleset or target object that you want to fully detach and choose EditDetach Fully. The system response depends on whether the fully detached object is a ruleset or a target object.

For a Ruleset

If the detached object is a ruleset, all occurrences of this ruleset disappear, except for one occurrence which remains in the model as a secondary root. If the detached object is a target object, every occurrence of the target object is removed from the model.

For a Target Object

15.9 Reattaching a Ruleset to a Different Object

A ruleset can be detached from one triggering object (or call rule) and reattached to another triggering object (or calling rule). For example, a ruleset can be moved from one call rule to another call rule.

To reattach a ruleset: Right-click the ruleset and choose Reattach from the popup menu. Or Select the ruleset that you want to reattach and choose EditReattach.
15-9

15

Working with the Rule Model Excluding a Ruleset or Target Object

3 Click the new triggering object or calling rule. The system response depends on the type of object or rule. For a Triggering Object The system response depends on whether or not this is the objects first dependent.

If this is the triggering objects first dependent, its position is determined automatically. If the triggering object already has dependents, the status line prompts you to choose a position. Click the position among the siblings where you want to place this copy of the ruleset.

For a Calling Rule

The system response depends on whether the calling rule is a fetch rule or a call rule.

If the calling rule is a fetch rule, the newly attached ruleset is a THEN ruleset. You can change the THEN ruleset to an ELSE ruleset via the ruleset dialog box. Double-click the newly attached THEN ruleset and in the ruleset dialog box that is displayed choose Else. If the calling rule is a call rule, the newly attached ruleset is an ELSE ruleset, even if you have not as yet attached a THEN ruleset to the call rule.

15.10 Excluding a Ruleset or Target Object

A ruleset or a concept can be excluded from a model. Excluding a ruleset or target object removes all instances of it from the rule model, but does not remove it from the knowledgebase. You can bring the object back into a model later.

A rule cannot be excluded.

To exclude a ruleset: Right-click the object and choose ExcludeSelected from the popup menu that is displayed. Or Select the object that you want to exclude and choose EditExclude.

15.11 Replacing a Ruleset

A ruleset (either a triggered ruleset or a nested ruleset) can be replaced with another existing ruleset.
15-10

Working with the Rule Model Rule Reengineering

For a Triggered Ruleset

To replace a ruleset:

1 Via the rule model, double-click the (red) handle attached to the ruleset that you want to replace. An appropriate dialog box is displayed depending if the ruleset is nested or not.

For a Nested Ruleset

2 Enter the name of the ruleset, in the Replace with drop-down editbox, that is to replace the selected ruleset. Use the drop-down editbox to list existing rulesets and to choose an existing ruleset. 3 Click OK.

15.12 Rule Reengineering

If a constructor was defined as a target object for a fetch or derivation rule, and then the constructor was reengineered into a concept, the
15-11

15

Working with the Rule Model Exporting Rules within Concept Models to External UML Tools

constructor still appears in the rule. You must reengineer the rule to update the reengineered target object in the rule.

To reengineer a fetch rule:

1 Right-click the rule. 2 Choose ObjectRule Reengineering.

15.13 Exporting Rules within Concept Models to External UML Tools

When concept models are exported to XMI, all associated rules are exported with them. The exported models can then be read by external UML tools. For information about how to export concept models, see "Exporting a Concept Model to an External UML Tool" on page 6-6.

15-12

Chapter 16 Using a Computation Rule

A computation rule is used for the following:

Store field values from the rule context into the triggering object. This is the method used to update field values in the triggering object. The rule syntax: ...IS STORED AS... is used to denote this. Display stored values on user forms. The rule syntax ... AND ECHOED ... is used for this. Calculate values for fields not in the triggering object, and to put these calculated values into the rule context to be used by other rules. The fields for which the values are being calculated must be defined in the knowledgebase. This is the method used to add field values not initially in the rule context to the rule context. The rule syntax: ...IS COMPUTED AS... is used to denote this.

16-1

16

Using a Computation Rule Specifying a Computation Rule

16.1 Specifying a Computation Rule

From the rule model, access the Computation Rule (200005) definition form and define the computation rule. For how to select the definition form see "Advancing a Rule to Design" on page 12-1:

1 Assign any rule options that you need. 2 Compose the rule. Enter the text of the computation rule in the Rule Text groupbox. See "Computation Rule Syntax" on page 16-3. Rule Editor assists in composing the rule text (see Chapter 13, Rule Editor)unless the RULEEDITOR OFF command is issued. Use the scroll bar to see all the lines of the rule. 3 If you require a list of existing temporary/global fields that are defined in the knowledgebase, click the TempFields button (see "Listing Temporary Fields" on page 12-7).
16-2

Using a Computation Rule Computation Rule Syntax

4 Click Apply. 5 Click Compile to implement the rule.

16.2 Computation Rule Syntax

Following is the syntax for the computation rule statement. Refer to "Making a Rule Conditional" on page 12-4 for the syntax of a conditional computation rule.

WHILE <field1> <expression>

Introduces a repeated computation rule. The clause after the DO keyword is repeated while the condition contained in the WHILE clause is valid. The name of the field used as a comparison in the WHILE clause. If no relationship is specified in the WHILE clause (EQ, NE etc.), EQ is assumed. A numeric or character expression comprising values (numbers, character strings or dates), fields and operators (+-*/):

A field can be from the triggering object, from a computed field from another rule, or from a global field (e.g. CURRENT-OPER). (See "Global Fields" on page 11-19 for information about global fields). If no relationship is specified (EQ, NE etc.), EQ is assumed.
16-3

16

Using a Computation Rule Computing a Value to be Stored and/or Displayed

STORED COMPUTED

The value is stored in the triggering class. (field2 must appear in the triggering class.) The value is assigned to field2 for use by other rules.

Example
PRICE is computed as QUANTITY * ITEM-PRICE.

16.3 Computing a Value to be Stored and/or Displayed

Values for fields defined in a triggering object can be updated by obtaining new values for them using a computation rule. The new field values can be: Stored in the object that triggered the rule Stored in the object that triggered the rule and displayed on a form Only displayed on a form

Calculating a Value to be Stored in the Triggering Object

If you want a calculated value stored in the database, ensure that the triggering object is the concept design where you want to store the value. Example: To calculate the price of an order as the unit price for the item multiplied by the quantity ordered use a computation rule. Since this information does not change after the order has been confirmed, it is convenient to store the information in the database. Therefore, attach the rule to a concept design, to be calculated as a consequence of an order being made (a consequence rule). Use a computation rule like the following:
ORDER-PRICE is stored as UNIT-PRICE * QUANTITY-ORDERED.

If you want to store a value in the database that is based on a calculation that uses a value not currently in the rule context, use a fetch rule to bring the needed value into the rule context. (See Chapter 18, Using a Fetch Rule).

Calculating a Value to be Stored and Displayed

If you want to store a calculated value in the database, and at the same time display the value on the data form which triggered the rule, echo the
16-4

Using a Computation Rule Computing a Value to be Stored and/or Displayed

calculated value. Echoing is a function that causes the database to be reread, so as to refresh the current data form with changes that might have occurred in the database. A value is echoed when the field is defined as an echo field both in the rule and in the data form where it is to be echoed. Example: To see the price of an order, calculated as the unit price for the item multiplied by the quantity ordered (see above), as the order is entered, while also storing the value in the database. Use a computation rule like the following:
ORDER-PRICE is stored as UNIT-PRICE*QUNTITY-ORDERED and echoed.

The additional clause AND ECHOED allows the field, Order Price, to be echoed on the form where the input was made which triggered the rule. Using the keyword ECHOED in a rule text causes the field value to be echoed not only on the current form but on all forms where the field appears. To limit the echo to a specific form define the echo from a field in a block by assigning the EchoedByRule option to the field. Assigning the EchoedByRule Option for the Field in a Form The EchoedByRule option must be assigned to the field via the form definition.

1 Select the design symbol from the rule model. Choose Object Concept Design. The Concept: Design form is displayed:

16-5

16

Using a Computation Rule Computing a Value to be Stored and/or Displayed

16-6

Using a Computation Rule Computing a Value to be Stored and/or Displayed

2 Right-click in the Design textbox and choose Forms from the popup menu displayed: The Constructor Forms form is accessed:

16-7

16

Using a Computation Rule Computing a Value to be Stored and/or Displayed

3 Right-click in the Form textbox for a particular form and select Detail from the popup menu that is displayed. The Form Definition form is accessed:

16-8

Using a Computation Rule Computing a Value to be Stored and/or Displayed

4 Click the Fields button on the Blocks tab page. The Fields in Block Definition form is accessed:

5 Select a field and assign EchoedByRule to the field in the form.

Fields can be retrieved from other concept designs and echoed to the form. In this case use a fetch rule with the clause AND ECHOED added to the fetch rule statement.

Calculating a Value Only for Display

If you only want to display the calculated value, use an operation (or a block in a form) as the triggering object.

Example
To see, on a daily basis, the length of time an employee has been with the company, use a computation rule to calculate the amount of time between the employee starting date and the current date. Since this information changes daily, it is not necessary to store the information in the database. Therefore, attach the rule to an operation, to be displayed when the employee information is displayed (an edit rule). Use a computation rule like the following:
DAYS-EMPLOYED is stored as CURRENT-DAY - START-EMPLOYMENT.

16-9

16

Using a Computation Rule Using Temporary Fields

The keyword STORED means that the result is stored in the triggering object. Therefore, the result is stored in Days Employed. The result is stored in the operation before the operation values are displayed and then displayed along with the other values.

Since the rule is attached to an operation, there is no need to specify that the result should be echoed to have its value displayed on the form.

The CURRENT-DATE field is a global field. It is always included in the rule context. (Start Employment is a concept field in the Employee concept and is therefore in the rule context). A stored value can also be used by other rules later on, as it is also included in the rule context.

The field that is used to display the result (Days Employed) should be defined in the target concept design as an operation field. Fields can be retrieved from other concept designs and stored in a triggering operation via a fetch rule. The retrieved fields are echoed to the form, when the operation is displayed. In this case, the clause AND ECHOED is not necessary in the fetch rule.

16.4 Using Temporary Fields

If you want to calculate a value for use later, by other rules, use the COMPUTED keyword in a computation rule. A computed field is considered by eMerge to be a temporary field (see "Defining a New Temporary Field in the Knowledgebase" on page 12-8). The temporary field must be defined as a field in the knowledgebase.

If you use the COMPUTED keyword in a rule statement for a field in a class, you receive an error when attempting to compile the rule.

Example: To calculate the date one week from today for use by other rules, use a computation rule like the following:
TEMP-DATE is computed as CURRENT-DATE + 7.

Temp Date is a temporary field and Current Date is a global field.

16.5 Initializing Values

If you want to initialize a value for use later, by other rules, use the COMPUTED keyword in a computation rule to calculate a value for the temporary field.
TEMP-SHIP-DATE is computed as RECEIVE-DATE + 10.
16-10

Using a Computation Rule Calculations Involving Date Fields and Hexadecimal Fields

You can also initialize a value dependent on whether a value in another concept exists. A fetch rule is used for this. The fetch rule can be conditional such that if the field exists, it is initialized with one value and if the field does not exists, it is initialized with another value. You can also set validation criteria to determine if the field exists. See "Initializing Values Using a Fetch Rule" on page 18-19.

16.6 Calculations Involving Date Fields and Hexadecimal Fields

Date Fields
Date fields can be used in computations, except for fields having monthyear format (e.g. 10.2001). Any calculation where dates are involved returns a value in days. For example, a rule calculating the length of time an employee has been with a company (e.g. CURRENT DATE - START EMPLOYMENT) returns the number of days. If you store the result in a date field, the number is displayed as a date. Example: To return a date when the delivery date for an order (RECEIVE-DATE + 7) is calculated, use a computation rule like the following:
SHIP-DATE is stored as RECEIVE-DATE + 7.

Include as part of the rule any necessary calculations to change the number of days to a different basis (e.g. years). Example: To calculate the number of years an employee has been with a company, use a computation rule like the following:
YEARS-EMPLOYED is stored as CURRENT-DATE START-EMPLOYMENT / 365.

The order of preference for the arithmetic operators (- and / in this example) follows the order they appear in the rule. That is * and / do not have a higher priority than + and -. The rule is equivalent to:
YEARS-EMPLOYED is stored as (CURRENT-DATE - START-EMPLOYMENT) / 365.

Hexadecimal Fields
Hexadecimal fields (e.g. option fields in eMerge forms) can be manipulated using the following operators:

16-11

16

Using a Computation Rule Calculating a Value Conditionally

Addition (+)

In the binary equivalent the following applies: 0+0 = 0 0+1 = 1 1+0= 1 1+1= 1 Example: C000+0004 = C004 4000+8000 = C000 C000+0400 = C400

Multiplication (*)

In the binary equivalent the following applies: 0*0 = 0 0*1 = 0 1*0= 0 1*1= 1 Example: C000*0004 = 0000 4000*8000 = 0000 C000*0400 = 0000

Subtraction (-)

In the binary equivalent the following applies: 0-0 = 0 0-1 = 0 1-0= 1 1-1= 0 Example: C000-0004 = C000 4000-8000 = 4000 C000-0400 = C000

16.7 Calculating a Value Conditionally

The same conditions that apply to unconditionally calculating a field value also apply to conditionally calculating a field value. Example: Calculate a value dependent on whether a condition is met. Upon hiring an employee his insurance rate for life insurance depends on his age. A different rate differential, dependent on the age of the
16-12

Using a Computation Rule Calculating a Value Dependent on the Operation Code

employee, is added to the insurance premium for employees older than age 50. All employees are older than 14 years. Before triggering this ruleset, an initial value for INSURANCE RATE is stored in the INSURANCE RATE field and a value for AGE is computed (not shown here). Use a computation rule like the following:
if AGE > 50 then INSURANCE-RATE is stored as INSURANCE-RATE+(AGE-50)*.0005 else INSURANCE-RATE is stored as INSURANCE-RATE + (AGE-14)*.0005.

16.8 Calculating a Value Dependent on the Operation Code

By assigning options you can change the default that causes a rule to be triggered. Refer to "Validating Fields in Other Concept Designs" on page 17-10 for an example of assigning the OnDelete option. Refer to the Form Reference for details of the options.

16.9 Calculating a Value Based on an Iterative Process

When a calculation requires a number of iterations to arrive at an answer, use a computation rule to loop until the required result. Example: is met. To continue to calculate the value of a field until a condition

Use a computation rule like the following:

while FILEDA is le FILEDB do FILEDC is stored as FIELDC * 2 FIELDA is stored as FILEDA + 1.

As long as Fielda is less than or equal to Fieldb, Fieldc is multiplied by two and Fielda is increased by one. Assuming the starting values for Fielda is 5, Fieldb is 8 and Fieldc is 1 the result is: Value of FIELDA Value of FIELDB Value of FIELDC 5 6 7 8 8 8 2 (1 * 2) 4 (2 * 2) 8(4 * 2) New FIELDA Value 6 (5 + 1) 7 (6 + 1) 8 (7 + 1)

16-13

16

Using a Computation Rule Calculating a Value Based on an Iterative Process

Value of FIELDA Value of FIELDB Value of FIELDC 8 9 8 8 16 (8 * 2) 16

New FIELDA Value 9 (8 + 1) 9

When the value of Fielda is 9 it is greater than Fieldb and processing stops.

Up to 500 iterations are allowed.

16-14

Chapter 17 Using a Validation Rule

A validation rule is used for the following: Validate data to ensure that what is entered is logical and valid Validate data within the same target object beyond the checking done via options or field definitions (e.g. possible values)

Fetch rules (defined in the Fetch Rule form) are used to check data across target objects (see "Using a Fetch Rule" on page 18-1).

17-1

17

Using a Validation Rule Specifying a Validation Rule

17.1 Specifying a Validation Rule

Use a validation rule to test a specific condition and to return an error or warning if the condition is not met. From the rule model, access the Validation Rule (200004) definition form to define the validation rule:

1 Assign any rule options that you need. 2 In the Erroneous Field textboxes (Error Message tab), enter the number and name of the field on which the pointer is to be positioned whenever the validation rule fails. In the first textbox enter the number of the field. In the second textbox enter the name of the field. If the field name is unique, it suffices to identify the Erroneous Field only by its name.

17-2

If Warning is assigned to the validation rule, entering an Erroneous Field is irrelevant. When a validation rule that has been assigned Warning fails, the processing continues after the error message containing the warning is issued.

Using a Validation Rule Validation Rule Syntax

3 In the Message textbox (Error Message tab) enter the message displayed when the validation fails. If a message is not specified, Business Integrity Server displays a message when the validation rule fails.

If Warning is assigned to the rule, the error message is issued as a warning, and the processing continues after the error message is issued.

Add an asterisk (*) at the end of the message to display information about the work area that caused the error. Put the asterisk after an appropriate connecting word. Example: The following error message:

YOU CANNOT CLOSE * is displayed as:

ERR2404 YOU CANNOT CLOSE PROJECT "358"

4 Compose the rule. Enter the text of the validation rule in the Rule Text field. See "Validation Rule Syntax" on page 17-3. Rule Editor assists in composing the rule text (see Chapter 13, Rule Editor)unless the RULEEDITOR OFF command is issued.

5 If you require a list of existing temporary/global fields that are defined in

Use the scroll bar to see all the lines of rule text.

the knowledgebase, click the TempFields button (see "Listing Temporary Fields" on page 12-7). 6 Click Apply. 7 Click Compile to implement the rule.

17.2 Validation Rule Syntax

Following is the syntax for the validation rule statement. Refer to "Conditional Validation" on page 17-5 for the syntax of the conditional validation rule.

17-3

17

Using a Validation Rule Validating Against a Constant or Set of Constants

Where: <field> <value> The name of the field to be validated. The value against which the field is validated. The value can be a single value, a range of values (value x to value z), a list of values (value x, value y), or a combination. Specifying the keyword DEFAULT checks the field against its default value. If a comparison keyword (e.g. EQ, NE, ...) is not specified, EQ is assumed.

Example
order-date must be ge current-date.

17.3 Validating Against a Constant or Set of Constants

Normally, a field value is checked against a constant value by assigning possible values to the field. However, in a number of situations, rules must be used instead. The constant value can consist of characters, numbers, dates or calculated values. If the constant value is a character string, it must be surrounded by single quotes and it must be uppercase letters (e.g. STRING). The set of constants can be either distinct values, a range of values, or a combination of distinct values and ranges.

Processing via possible values is more efficient than processing via rules.

Ensuring Field Validity

The value of a field can be changed by a rule such that it becomes invalid. For example, an amount is subtracted from a field value via a rule. The new value can be negative even if a negative value is not valid for the field. Another rule is needed to prevent this situation from being accepted. Example: FIELDA must be greater than or equal to zero. Use a validation rule similar to the following to prevent the field value from being accepted when it is negative:
FIELDA must be ge 0.

The validation fails if FIELDA is less than zero.

17-4

A negative value can be valid if the MayBeNegative option is assigned to the field in the Concept (accessed from a concept in a model by right-clicking the concept and

Using a Validation Rule Validating Against a Constant or Set of Constants

selecting Object>Fields). The assumption for the above rule is that the MayBeNegative option was not assigned to the field and that the field is given a negative value via a rule. The above validation rule prevents this situation from being accepted.

Conditional Validation
Sometimes it is necessary to perform a validation when another field has a certain value. The validation is performed conditionally, i.e. depending on the outcome of the logical test performed on a data value. Example: SALES. FIELDA must equal either: 1, 3 or 5 if the value of FIELDB is

Use a validation rule similar to the following:

if FIELDB = "SALES" then FIELDA must be eq 1, 3, 5.

Checking Possible Values

Possible values define the acceptable values that can be entered into a field on a form. A field value is checked automatically against the possible values allowed for the field when the user enters data via a form. However, a rule can calculate a value which is an invalid possible field value. To prevent calculated field values from assuming unacceptable values, a rule is needed to check the field value against its possible values. Rule Validation for Possible Values The check performed is to ascertain that a value is not equal to a list of values. The possible values have to be the reverse of the list (which is not obvious to whoever needs to maintain this list). For example, the value cannot be one of the following prime numbers: 1 2, 3, 5, 7, 11, 13, 17, 19. The possible value list is: 4, 6, 8, 9, 10, 12, 14, 15, 16, 18, 20.
Since the possible values for the field are all the nonprime numbers (up to 20) a user is prevented from entering any prime number (up to 20) into a data entry form. However, a rule is needed to check that no prime number (up to 20) was calculated for the field value via a rule.

Example

FIELDA is compared to the prime numbers 1, 2, 3, 5, 7, 11, 13, 17 and 19. Use a validation rule similar to the following:

/* FIELDA cannot be one of the prime numbers up to 20 FIELDA must not be eq 1, 3, 5, 7, 11, 13, 17, 19.

The validation fails if FIELDA equals any of these numbers.

17-5

17

Using a Validation Rule Validating Against a Calculated Value

Note that a comment has been added as part of the text, explaining the meaning behind the numbers specified in the rule.

17.4 Validating Against a Calculated Value

You can use arithmetic expressions as part of the validation. Example: The value of FIELDA must be twice the value of FIELDB. Use a validation rule like the following:
FIELDA must be FIELDB * 2.

17.5 Checking Against Another Field

Checking a field value against another field value cannot be done using possible values. The field value to be checked against may be in the same concept design or may be defined in another design. If the field value is in another concept design a fetch rule is needed to bring the field value into the rule context in order to perform the validation (see Chapter 18, Using a Fetch Rule).

The Field is in the Same Concept Design

Check a field value against another field value in the same concept design using validation rules. Use a validation rule like the following:
FIELDA must be lt FIELDB.

The Field is a Path Field

Path fields (i.e. a key field) are included in the initial rule context. Check the field value against the path field value via a validation rule. The validation rule shown above validates FIELDA against the path field, where FIELDB is a path field.

17.6 Checking Validity Against a Mask

Check a field against a specified format by using a mask. The mask is a string which is used as a pattern to match against the field value:

17-6

Using a Validation Rule Checking Validity Against a Mask

Example
If FIELDA is a name, input of a name must finish with a space followed by a single letter (surname, space, initial letter of first namee.g. WHITE J.). Use a validation rule like the following:
FIELDA must be masked-by @* %.@.

The validation fails if the value of FIELDA does not match the mask. The mask string is surrounded by quotes. The mask itself starts and finishes with the @ character. When the value of FIELDA is a null/blank value the masking process produces a null/blank result and the validation is successful (condition is True).

Special Characters that can be Used in a Mask

The following special characters can be used in the mask: * A variable length wildcard character: any character combination, including a null string. % # A single wildcard character. A single wildcard digit.

The following examples show a mask, a field value and whether they match. To allow both uppercase and lowercase letters in a character field, assign the Mixed option to the field via the Concept form (accessed
from a concept in a model by right-clicking the concept and selecting Object>Fields).

mask @A*@

Field Value Match AAAA ABCD aaaa Yes Yes Yes No

Comment

field value is translated to uppercase, before the match with the mask field value is uppercase and mask starts with lowercase a

@a*@

ABCD

17-7

17

Using a Validation Rule Checking Validity When Using Special Characters

mask

Field Value Match aaaa No

Comment field value is translated to uppercase before the match with the mask, mask starts with lowercase a field value is translated to uppercase before the match with the mask. second character is not a C. The field value includes 4 digits.

@%C%@ aca ABCA @###@ 123 1234

Yes No Yes No

A mask can also be used to tailor an input value. See the General Reference for details.

17.7 Checking Validity When Using Special Characters

When a validation rule uses special characters in a condition, pattern matching is invoked. Special characters are used in patterns as masks (see"Special Characters that can be Used in a Mask" on page 17-7). If one of these special characters is the target for the condition, the special character is evaluated as a mask character and not as the character itself. Example: The following validation rule is intended to validate if FIELDB is equal to the special character #:
FIELDB must equal # .

Since pattern matching is invoked in this case, the special character (#) is treated as a mask and the expression is checked to validate if FIELDA is equal to a numeric digit and not to the # itself as intended. The following rule statements achieve the intended validation:
FIELDA is computed as # . FIELDB must be equal FIELDA.

17.8 Validating a Field Conditionally

The same conditions that apply to validating a field value unconditionally also apply to checking a field value conditionally.

17-8

Using a Validation Rule Validating a Field Dependent on the Operation Code

Example: Conditionally validate a field value against a constant value, or against another field value in the rule context (if necessary add the field value to the rule context via a fetch rule). Use a validation rule like the following:
if FIELDA is ge 65 and FIELDB = M then FIELDC must be eq FIELDE or FIELDC must be eq 1, 3, to 7.

The = symbol and the eq keyword are synonymous.

The AND keyword in the condition specified in the first line means that both of the conditions must be met for the check (specified in the second line) to be carried out. The OR keyword in the check (specified in the second line) means that processing continues as long as one of the two checks is successful.

17.9 Validating a Field Dependent on the Operation Code

By default a validation rule is triggered only for an insert or change operation. By assigning options, you can change what causes a rule to be triggered. Refer to the Form Reference for details of the options.

17-9

17

Using a Validation Rule Validating Fields in Other Concept Designs

Example: To set a rule that it is only executed when the operation is delete, assign the OnDelete option to the rule:

NotOnChange, NotOnDelete, NotOnInsert, OnChange, OnEdit, OnInsert are also dependent on the operation code. By default, a validation rule is not triggered when the operation is delete, only when it is insert or change. All other rule types are triggered when the operation is insert, change or delete.

17.10 Validating Fields in Other Concept Designs

When the data to be checked is not part of the rule context, a fetch rule is used to retrieve the data from the target object into the rule context. The fetch rule itself can be used to check certain situations, without the need to follow it with a validation rule. See Checking Fields in Other Target Objects on page 18-16.

17-10

Using a Validation Rule Continuing Processing After a Validation Fails

17.11 Continuing Processing After a Validation Fails

By default, if a validation fails, eMerge returns to the situation that existed prior to the input that led to the error. If you only want to use the check as a warning, assign the Warning option on the Validation Rule. When a validation fails, the error message defined for the rule is displayed as a warning, and processing continues.

17.12 Ensuring that a Validation Fails

If, as part of the process you must ensure that a validation fails, use a global field (see "Global Fields" on page 11-19). Example: You want to check if a field exists in another concept design, and to stop processing if it exists. Use a fetch rule to fetch the field from the other concept design. If the field does not exist, continue processing (see details about the IgnoreMissingTarget option). If the field does exists and the fetch is successful, use a validation rule which must fail, in order to ensure that processing stops:
CURRENT-OPER must be eq 0.

The CURRENT OPER global field is set to the operation currently being processed. The value of this field can never be zero and, therefore, the rule fails and processing stops. The above validation is executed when inserting data. When changing data, since no fields in the triggering concept design are referenced in the above rule, the rule is not executed. To ensure that the rule is executed in a change situation, include a field from the concept design (FIELDA) in the rule as a trigger:
FIELDA is trigger and CURRENT-OPER must eq 0.

The trigger field informs eMerge that the concept design is assumed to have changed. The rule is therefore executed.

17-11

17

Using a Validation Rule Ensuring that a Validation Fails

17-12

Chapter 18 Using a Fetch Rule

Fetch rules are used to retrieve data from a target data object occurrence which is not the current triggering object occurrence. The target object can be a concept, a class in a composite or a constructor. The triggering object can be, a concept, class, operation, program, query, block in a form, or a constructor. The field values in the target occurrence are added to the rule context. You can retrieve the following:

Values from a specific target occurrence. Values from a group of target occurrences. Values from a target occurrence that actually exists, whose key value is closest to the key value of a specific target occurrence.

The target for the fetch rule can be specified via: rule definition form See "Specifying a Fetch Rule" on page 18-1. rule syntax See "Target Specification via Fetch Rule Syntax" on page 18-22. You can also use a fetch rule to check if data does or does not exist. That is, a fetch rule can be used to check for the existence or nonexistence of a value elsewhere in the database.

You cannot fetch updated values from a specific target object occurrence if the values were updated by a derivation rule triggered by the same triggering object.

18.1 Specifying a Fetch Rule

Use a fetch rule to retrieve data from the database that is not currently available in the triggering object or the rule context.

18-1

18

Using a Fetch Rule Specifying a Fetch Rule

Placing the Symbol in the Rule Model

1 Via Modeler, access the rule model for the concept that requires the fetch rule. 2 Select the ruleset in the rule model to which you want to attach the fetch rule. 3 Click the Fetch button on the Modeler toolbar. The following menu is displayed:

4 Choose Fetch. The Fetch Rule dialog box is displayed:

5 Enter a name for the fetch rule in the Name textbox. 6 Select a target from the Type drop-down listbox. 7 Click OK. The rule symbol for the fetch rule appears in the rule model:

Accessing the Fetch Rule Form

1 From the rule model (click the Rule button), access the Fetch Rule definition form to define the fetch rule.

18-2

Using a Fetch Rule Specifying a Fetch Rule

The target tab lists target information depending on the type of the target objecte.g. concept, class in a composite, or constructor. If the target is a concept, the Fetch Rule (200006) form is displayed:

1 Assign any rule options that you need. 2 To view target fields, click the TargetFields button (Target tab). If the concept is in the Design or Implementation stage the Design Fields (200027) form is displayed. If the target concept is in the Analysis stage the Concept Fields (200028) form is displayed:

18-3

18

Using a Fetch Rule Specifying a Fetch Rule

If the target is a class in a composite or a constructor then the parallel Fetch Rule (200032) form is displayed. When the TargetFields button is clicked the following forms are displayed: If the target is a class in a composite, the Fields in Class (2081) form. If the target is a concstructor, the Constructor Fields (2080) form.

Viewing Triggering Objects

1 To view triggering objects for the rule, right-click in the Ruleset textbox and select Triggering Objects from the pop-up menu that is displayed. The triggering form displayed depends on the type of triggering object (i.e. concept, class, constructor). For a trigering concept the Triggering Concepts (200037) form is displayed:

18-4

Using a Fetch Rule Specifying a Fetch Rule

18-5

18

Using a Fetch Rule Specifying a Fetch Rule

Click the OtherTrigger button to view other triggering objects. The Rulesets: Triggering Objects form is displayed:

2 To view the triggering fields, right-click with the pointer on a particular triggering object and select Fields from the pop-up menu that is displayed. The form displayed depends on the triggering object: For a concept: If the concept is Implemented the Design Fields (200027) form is displayed listing the triggering fields (otherwise, the Concept Fields (200028) form is displayed):

For a class: the Field in Class (200068) form is displayed listing the triggering fields

18-6

Using a Fetch Rule Specifying a Fetch Rule

For an operation: the Operation (200069) form is displayed listing the triggering fields. For programs/queries: the Program (200072) form is displayed listing the triggering fields. For a constructor: the Constructor Fields (2080) form is displayed listing the triggering fields. For an edit operation: the Oper Target Cls (200097) form is displayed listing the triggering fields. For a form: the Block Operation (200098) form is displayed listing the triggering fields.

Defining Error Handling

1 Select the Error Message tab. 2 In the Message field, enter the message that is displayed if the fetch fails. If a fetch rule fails and a message was not specified, Business Integrity Server displays a message. If Warning (Error Message tab) is assigned to the rule, the error message is issued as a warning, and the processing continues after the error message is issued. Add an asterisk (*) at the end of the message to display information about the work area which caused the error. Put the asterisk after an appropriate connecting word. Example: The following error message:

YOU CANNOT CLOSE * is displayed as:

ERR2404 YOU CANNOT CLOSE PROJECT "358"

Add two asterisks (**) at the end of the message to display the context of the target object whose location failed. Example: The following error message:

YOU CANNOT CLOSE ** is displayed as:

ERR2404 YOU CANNOT CLOSE PROJECT "358" ASSIGNMENT "1"

3 In the first textbox of Erroneous Field enter the number of the field on which the pointer should be positioned whenever the fetch rule fails. In the second textbox enter the name of the field on which the pointer

18-7

18

Using a Fetch Rule Specifying a Fetch Rule

should be positioned. If the field name is unique, it is possible to identify the Erroneous Field only by its name.

If Warning (Error Message tab) is assigned to the fetch rule, entering an Erroneous Field is irrelevant. When a fetch rule that has been assigned Warning fails, the processing continues after the error message is issued as a warning.

Composing the Rule Text

1 Enter the text of the fetch rule in the Rule Text field. See "Fetch Rule Syntax" on page 18-9. To avoid ambiguities, a field referenced in the rule text should be referenced by its number as well as by its name (e.g. FIELDA #3427) Rule Editor assists in composing the rule text (see Chapter 13, Rule Editor)unless the RULEEDITOR OFF command is issued. If any nested rulesets were specified in the rule model, the rule text has been automatically inserted. (See "Automatic Rule Text" on page 18-10.) Any fields that are referred to in a rule must be accessible to the rule. See "Defining Rules for a Ruleset" on page 11-16 for more information. 2 Click the TempFields button to view the temporary fields currently defined in the knowledgebase.

3 Click OK.

Use the scroll bar to see all the lines of the Rule Text field.

Compiling the Rule

Click the Compile button to implement the rule.

18-8

Using a Fetch Rule Fetch Rule Syntax

18.2 Fetch Rule Syntax

Following is the syntax for the fetch rule statement:

USE

Introduces a fetch rule which calls another ruleset. The USE keyword is optional, unless another ruleset is called as part of the statement or the THEN keyword is used. Introduces a break repeated fetch rule. The fetch clause (after the <expression>) is repeated for as long as the condition contained in the WHILE clause is valid. A numeric or character expression comprising values (numbers, character strings or dates), fields and operators (+-*/): Introduces a repeated fetch rule. The value of <field2> is fetched for every occurrence where <field1> is the key field or the path field. The name of the field used to identify the target data object: either as a path field to the target data object (using the PATH keyword) or as the key field of the target data object (using the TARGETKEY keyword). The entire path and/or key must be specified. Specifies that <field1> is the path field to the target data object. Specifies that <field1> is the key field of the target data object. Precedes the retrieval of <field2> from the target data object if the fetch is successful. The name of the field to be retrieved (fetched) from the target data object.
18-9

WHILE

<expression> WHERE <field1>

PATH TARGETKEY THEN <field2>

18

Using a Fetch Rule Fetch Rule Syntax

STORED THEN CALL <ruleset1> ELSE CALL <ruleset2>

The value is stored in the triggering data object. (<field2> must appear in the triggering data object.) Precedes the ruleset that is called if the fetch is successful. If an ELSE clause is used, the THEN keyword must be used. Calls the ruleset to be nested. The name (or number) of the ruleset to be called if the fetch is successful. Precedes the ruleset that is called if the fetch is unsuccessful. The name (or number) of the ruleset to be called if the fetch is unsuccessful.

Example
item-no is targetkey item-price is fetched and stored.

Automatic Rule Text

Some of the rule text for nested rulesets is inserted automatically. If you only specified a THEN ruleset in the rule model, the rule text entered for you in the Rule Text field has the following format:
THEN CALL ruleset_name #ruleset_no .

If you only specified an ELSE ruleset in the rule model, the rule text entered for you in the Rule Text field has the following format:
ELSE CALL ruleset_name #ruleset_no .

If you specified a THEN ruleset and an ELSE ruleset in the rule model, the rule text entered for you in the Rule Text field has the following format:
THEN CALL ruleset_name #ruleset_no ELSE CALL ruleset_name #ruleset_no .

18-10

Using a Fetch Rule Retrieving a Value From a Target Occurrence

Once you make any change to the text of a fetch rule, the automatic ruleset text mechanism is disabled, and the rule text for nested rulesets must be entered manually.

Manipulating a Nested Ruleset

For information on how to manipulate a nested ruleset (e.g. add, copy, replace, reattach, deactivate, delete, or exclude) see Chapter 15, Working with the Rule Model.

18.3 Retrieving a Value From a Target Occurrence

Example: To fetch the quantity of an item from the inventory into the rule context. Use a fetch rule like the following:
FIELDZ is targetkey FIELDZ1 is fetched.
FIELDZ is the key field in the target object. The field must also exist in the rule context. The value of FIELDZ1 is retrieved for further processing.

FIELDZ1 must not be defined as a field in the triggering object. (See below for the case where the value of fieldz1 is stored in the triggering object, in which case the field must exist in the triggering object.)

18.4 Storing a Retrieved Value

If you want to store a value in the triggering object, based on a value not in the rule context, use the STORED keyword. Example: To fetch, and store in the order, the price of an item from the inventory. Use a fetch rule like the following:
ITEM-ID is targetkey ITEM-PRICE is fetched and stored.

The value of Item-Price is retrieved and stored in the triggering object.

Item-Price must also be defined as a field in the triggering object.

The whole target object hierarchy is retrieved. However, only the fields in the target object that are specified in the rule are added to the rule context.
18-11

18

Using a Fetch Rule Retrieving the Closest Existing Value

Example: To retrieve two fields, one to be used for further processing and the other to be stored in the triggering object. Use a fetch rule like the following:
ITEM-ID is targetkey ITEM-PRICE is fetched and stored QUANTITY-ON-HAND is fetched.

If Item-Price does not exist in the triggering object, but a field with the same data type and size does exist in the triggering object (e.g. FIELDA), the field value (for Item-Price) can still be fetched from the target object and stored in the triggering object, as follows:
ITEM-ID is targetkey FIELDA is fetched from ITEM-PRICE and stored.

Since the whole target object hierarchy is retrieved, any fetches to other objects in the hierarchy do not require further disk access. All fetches to objects in the same hierarchy should be done one after the other, wherever possible, to improve performance.

18.5 Retrieving the Closest Existing Value

If a target occurrence does not exist (instead of failing), you can automatically retrieve another target occurrence (of the same type), that actually exists in the database. The target occurrence retrieved is the one whose key value equals the key value specified, or the closest values less than the key value.

It does not matter how the occurrences are sorted. The closest value is always the closest value less than the key value specified.

Example: Fetch a currency exchange rate from a list of currency exchange rates, where the key is the date. If the exchange rate requested does not exist for the given date, the exchange rate for the previous date is still valid. The value to be fetched is the actual exchange rate that applies to the date given, which is the exchange rate for the closest date in the past. Use a fetch rule like the following:
FIELDZ is actual targetkey FIELDZ1 is fetched.

The ACTUAL keyword means that the value that actually exists in the database, that is equal to, or the closest value less than, the target key

18-12

Using a Fetch Rule Retrieving a Dependent Target Occurrence

value, should be fetched. The value fetched depends on whether the data is sorted ascending or descending. When using the ACTUAL keyword in a fetch rule, for a key that is a multiple field key, the targetkey statements containing the ACTUAL keyword must be the last targetkey statements.
ACTUAL

Example: A key has the following key values: k1, k2, k3, and k4. The keyword is used in the last targetkey statement:

K1, K2 are targetkey K3 is targetkey K4 is actual targetkey FIELDZ2 is fetched.

18.6 Retrieving a Dependent Target Occurrence

If the target is a dependent object, the fetch rule must include the path fields needed to fetch the target object.

The path fields must be available in the rule context for the triggering object.

18.7 Retrieving an Occurrence from the Same Object Hierarchy

If the target occurrence is in the same hierarchy as the triggering object occurrence, the fetch rule must include this information. The information is included by assigning an option as part of the definition of the fetch rule.

18-13

18

Using a Fetch Rule Retrieving an Occurrence from the Same Object Hierarchy

For example, the target object occurrence is in the same branch of the same triggering object hierarchy:

Or the target object is in a different branch of the same triggering object hierarchy:

To specify that the target is in the same branch in the same of the triggering hierarchy, assign the SameBranch option (Target tab > Memory category) to the fetch rule. If you have a fetch from a target in the same branch of the triggering hierarchy, and you do not assign either the SameBranch or SameComposite option (Target tab > Memory category), you receive an error.

18-14

Using a Fetch Rule Retrieving a Group of Target Occurrences

You can assign the SameComposite option instead of the SameBranch option without receiving an error. However, this is less efficient.

To specify that the target is in a different branch of the same triggering object hierarchy, assign the SameComposite option. If you do not know whether the target object for a fetch rule will be in the same hierarchy as the triggering object occurrence, assign the MaySameComposite option (Target tab > Memory category).

18.8 Retrieving a Group of Target Occurrences

If you want to retrieve fields from more than one target occurrence, use a repeated fetch rule. A repeated fetch adds the fetched fields for every target occurrence to the rule context, instead of the fields from a single occurrence. The following diagram shows a file containing six occurrences (A to F) of a target hierarchy. Each of the independent target object occurrences is a parent to a number of dependent occurrences (A1...A4, B1... etc.):

Do not use a repeated fetch to retrieve a whole file (e.g. A to F) if the file is large. Use the repeated fetch to retrieve values from dependent target objects (e.g. to retrieve values from A1 to A4). Example To add a fixed additional increase to the salary of any employee who receives a salary rise and who has more than three children. A repeated fetch to every occurrence of the EMPLOYEE CHILD object occurrence for the specific employee is needed. Use a repeated fetch rule like the following generalized fetch rule:
where EMPLOYEE-ID is path call ADD-SALARY.

18-15

18

Using a Fetch Rule Checking Fields in Other Target Objects

Note the following about this fetch rule: 1. The Repeated option is assigned automatically on compiling the rule. This option flags the rule as a repeated fetch rule and is assigned when the rule includes the WHERE keyword. 2. Only the path to the target object needs to be specified (where EMPLOYEE-ID is path). Since the fetch is to every occurrence of the target object there is no point in specifying a target key. 3. The calculation necessary to count the number of children is done in a separate rule (which is defined in a ruleset called by the fetch rule). You should not do calculations in a fetch rule. Refer to "Calling a Ruleset Conditionally" on page 20-6 for details about called rulesets. 4. In addition to the calculation being done by a separate computation rule in another ruleset, a computation rule was also necessary before the repeated fetch rule to initialize the counter. Each time the fetch was successful, the counter was increased by one (counter is computed as counter + 1). 5. Since, in this case, the fetch was to a dependent object in the same object hierarchy, the SameBranch option was assigned to the first rule. Break for Fetch Repeated Normally, a fetch repeated loop continues until all occurrences are fetched. You can break a fetch repeated loop by using a WHILE condition. In the fetch rule syntax, the keyword WHILE is used to indicate that the loop is conditional. An <expression> follows the WHILE keyword that defines the while condition. This is followed by the keyword WHERE and the remaining fetch rule statements. (See Specifying a Fetch Rule on page 18-1).

18.9 Checking Fields in Other Target Objects

When the data to be checked is not part of the rule context a fetch rule is used to bring the data into the rule context. The fetch rule itself can be used to check certain situations, without the need to follow it with a validation rule.

Checking if a Value Exists in Another Target Object

If a field in another target object occurrence is a key field, successfully fetching the field proves its existence.

18-16

Using a Fetch Rule Checking Fields in Other Target Objects

Example: Fieldz, is the key field in the other target object occurrence and exists in the triggering object. If a target object occurrence with the triggering object value for Fieldz is found, processing continues. Use a fetch rule as follows:
FIELDZ is targetkey.

Checking that a Value Does Not Exist in Another Target Object

If a field in another target object occurrence is a key field, unsuccessfully attempting to fetch the field proves that the occurrence of the other target object does not exist. Example: Fieldz is the key field in the target object and exists in the triggering object. If a target object occurrence with the triggering object value for Fieldz is not found, an error situation is created. The error proves that the target object occurrence does not exist. Normally, on encountering an error situation, eMerge returns to the situation that existed prior to the input that led to the error. To ensure that processing continues as if an error was not encountered, do one of the following in the Fetch Rule (200006) form:

Assign the Warning option (Error Message tab). A warning message is issued and processing continues. Assign the IgnoreMissingTarget option (Target tab > Access category). The error (the target object occurrence is missing) is ignored and processing continues.

Checks on Values in a Target Object

If a field in another target object occurrence is not a key field, you can perform certain checks directly on the field value in the target object. Use a fetch rule to perform the check. Example: Fieldz is the key field in the target object and exists in the triggering object. If a target object occurrence with the triggering object value for Fieldz is found, a field in the triggering object (Fielda) is checked against a field in the target object (Fieldz1). Use a fetch rule like the following:
FIELDZ is targetkey FIELDA is verified as eq with FIELDZ1.

18-17

18

Using a Fetch Rule Fetching a Value Conditionally

The field in the triggering object (Fielda) must be checked against the field in the target object (Fieldz1) and not vice versa. If you attempt to check the field in the target object against the field in the triggering object you receive an error message, that the field is not in the rule context.

Ensuring that a Check Fails

If, as part of the process you must ensure that a check fails, use a global field (see "Global Fields" on page 11-19). Example: You want to check if a field exists in another target object, and to stop processing if it does exist. Use a fetch rule to fetch the field from the other target object. If the field does not exist, then continue processing (see details about the IgnoreMissingTarget option above). If the fetch is successful, use a validation rule which must fail, in order to ensure that processing stops:
CURRENT-OPER must eq 0.

The CURRENT OPER global field is set to the operation currently being processed. The value of this field can never be zero and, therefore, the rule fails and processing stops. The check is executed when inserting data. When changing data, since no fields in the triggering object are changed the rule is not executed. To ensure that the rule is executed in a change situation, include a field from the target object in the rule as a trigger:
FIELDA is targetkey CURRENT-OPER must be eq 0.

The trigger field informs eMerge that the target object is assumed to have changed. The rule is therefore executed.

18.10 Fetching a Value Conditionally

The same conditions that apply to fetching a field value unconditionally also apply to fetching a field value conditionally. Example: To fetch a value dependent on whether a condition is met. Use a fetch rule like the following:
use FIELDZ is targetkey then FIELDZ1 is fetched.
18-18

Using a Fetch Rule Initializing Values Using a Fetch Rule

The USE keyword introduces the conditional fetch rule.

The IF keyword can also be used to introduce a conditional fetch rule.

18.11 Initializing Values Using a Fetch Rule

Use a fetch rule to initialize a value dependent on whether a value in another target object exists. The fetch rule can be conditional such that if the field exists, it is initialized with one value and if the field does not exist, it is initialized with another value. You can set validation criteria to determine that the field exists.

Normally you should not use a fetch rule to perform a calculation. If you want to perform a calculation based on the results of a fetch, include a call to another ruleset. Use a computation rule in the other ruleset to do the calculation. For an example refer to "Retrieving a Group of Target Occurrences" on page 18-15. For details about calling other rulesets from within a rule refer to "Using a Call Rule" on page 20-1.

Example: Fieldz is the key field in the target object and exists in the triggering object. If a target occurrence is found, where the key field value is the same as the value of Fieldz in the triggering object, a temporary field is initialized to 1. If the target occurrence is not found, the temporary field is initialized to 0. Use a fetch rule similar to the following:
use FIELDZ is targetkey then TEMP-FIELD1 is computed as 1 else TEMP-FIELD2 is computed as 0.

The keyword USE (or the synonymous keyword IF) in a fetch rule indicates that the rule is conditional.

Example: Fieldz is the key field in the target object and exists in the triggering object. If a target object occurrence is found, where the key field value is the same as the value of Fieldz in the triggering object, a field in the triggering object (Fielda) is checked against a field in the target object (Fieldz1). If the check is successful, a temporary field is initialized to 1. If the check is not successful, the temporary field is initialized to 0. If the target object occurrence is not found, the temporary field is initialized to 0. Use a fetch rule like the following, where the verification line has been added:

18-19

18

Using a Fetch Rule Calculating a Value Dependent on the Operation Code

use FIELDZ is targetkey FIELDA is verified as eq with FIELDZ1 then TEMP-FIELD1 is computed as 1 else TEMP-FIELD2 is computed as 0.

A field in the triggering object (Fielda) is checked against the field in the target object (Fieldz1) and not vice versa. If you attempt to check the field in the target object against the field in the triggering object you receive an error message, that the field is not in the rule context. The fetch rule is not always successful. If the else statement was not included, then if the fetch or verification failed the rule would fail. When a fetch rule fails, if an error has not been defined, eMerge issues a relevant error message for the situation. If a target object occurrence is not found and an error message was not defined for the rule, a system error message is returned. If the verification fails, an error message is also returned. You can assign the IgnoreMissingTarget option (and the IgnoreMissingPath option) as part of the fetch rule definition in order that processing continue, as if the fetch was successful, even if the fetch fails (with the condition that no subsequent call rule exists within the ruleset).

18.12 Calculating a Value Dependent on the Operation Code

By assigning options you can change the default that causes a rule to be triggered. Refer to "Validating a Field Dependent on the Operation Code" on page 17-9 for an example of assigning the OnDelete option. Refer to the Form Reference for details of the options. If the rule is triggered by a change, the fetch rule might be executed twice: once using the values before the change and once using values after the change. For details of this feature and how to control it refer to "Controlling the Values Used by a Rule" on page 28-7).

18.13 Continuing Processing After a Fetch Fails

If the target object occurrence does not exist, or a target object occurrence in the path does not exist, an error occurs. To prevent the error occurring and to allow processing to continue via the Target tab on the Fetch Rule (200006) form and assign one or more of the following options:

18-20

Using a Fetch Rule Field Values in Rule Context

IgnoreMissingTarget Processing continues if the target object occurrence does not exist (and no subsequent call rule exists within the ruleset). IgnoreMissingPath Processing continues if an object occurrence does not exist in the path to the target object occurrence. Warning (Error Message tab) Processing continues and the error message defined for the rule (or the default eMerge error message if an error message is not defined) is displayed as a warning and not as an error.

When processing continues, any fields that the fetch rule would have added to the rule context are not added.

Using a Fetch Rule with the ForUpdate Option Assigned

When a fetch rule with the ForUpdate option (Target tab > Memory category) assigned to the target is used for accessing SQL, an update cursor is opened. If an update cursor is not available (or if update cursors were not defined), an error is issued (Error 3520 or Error 3522). If however, you want processing to continue (even though an update cursor is not available) using a read-only cursor, assign the CursorAvailableForUpd option on the SQL DBMS Definition (23407) form. If the CursorAvailableForUpd option is assigned and an update cursor and a read-only cursor are not available, an error is issued.

It is not recommended to use the CursorAvailableForUpd option. If an error occurs using update cursors, it is recommended to increase the number of update cursors available (see the DBMS Guide). If you do not need update cursors, do not assign the ForUpdate option to the fetch rule.

18.14 Field Values in Rule Context

Any computation involving field values that have different lengths or types changes the value of the target field in the rule context. For example, in the following fetch rule:
ITEM is targetkey for ITEM-PRICE.

If the length of the two fields are not the same, the value for ITEM-PRICE is implicitly changed in the rule context.

18-21

18

Using a Fetch Rule Target Specification via Fetch Rule Syntax

18.15 Target Specification via Fetch Rule Syntax

There are two ways to specify a target definition via the fetch rule syntax: staticallythe name or number of the composite/class is explicitly listed in the rule dynamicallythe value for the composite/class is calculated dynamically during application processing

To specify a target via the rule syntax:

1 From the Logic tab on the Navigation pane of Development Workbench access the definition form for the rule. 2 Leave the target textbox blank. 3 Compose the fetch rule using the syntax listed below ("Fetch Rule Syntax with Target Specification" on page 18-23). 4 Specify the target in the rule syntax.

Options
Options are listed in the {f-options} syntax. See Form Reference for an explanation of the options.

18-22

Using a Fetch Rule Target Specification via Fetch Rule Syntax

Fetch Rule Syntax with Target Specification

18-23

18

Using a Fetch Rule Specifying a Find Action for a Fetch Rule

18.16 Specifying a Find Action for a Fetch Rule

The type of fetch can be controlled by specifying a find action for finding the target of the fetch rule. The following are the find actions: LessThan LessOrEqualThan GreaterThan GreaterOrEqualThan Equal The default find action is Equal. When a fetch rule with a find action is implemented, target occurrences are fetched from the context according to the target value and find action. If the target value is empty, occurrences are fetched in the following order: For an ascending order class: Find Action LessThan LessOrEqualThan GreateThan GreaterOrEqualThan Equal Fetched Order maximum field value to minimum field value maximum field value to minimum field value minimum field value to maximum field value minimum field value to maximum field value error For a descending order class:

18-24

Using a Fetch Rule Specifying a Find Action for a Fetch Rule

Find Action LessThan LessOrEqualThan GreateThan GreaterOrEqualThan Equal

Fetched Value minimum field value to maximum field value minimum field value to maximum field value maximum field value to minimum field value maximum field value to minimum field value error

To specify a find action for a fetch rule:

1 Access the fetch rule definition form. 2 Click the Target tab and click in the Concept textbox. The Properties form for the target tab is displayed.

3 Click in the Find Action property and select a find action for the fetch rule:

18-25

18

Using a Fetch Rule Fetching Information via All Paths to Target Class

18.17 Fetching Information via All Paths to Target Class

A fetch rule fetches information from a target class via a specified path. It is also possible to fetch information from all classes below a specified class until (and including) the target class. This type of fetch retrieves all occurrences, for all paths starting at the specified class and ending at the target class. Naturally, the starting class should be a parent of the target class. Example: Class A contains dependent classes B, C and D. Class B has 2 occurrences B1 and B2. Class C has 2 occurrences C1 and C2. Class D has 2 occurrences D1 and D2. The class occurrence hierarchy is depicted below:
Class Hierarchy A

B1

B2

C1

C2

C1

C2

D1

D2

D1

D2

D1

D2

D1

D2

A fetch rule with class D as target retrieves all matching information from occurrences of the target class via a specific path, e.g. A-B1-C1-D1 and A-B1-C1-D2. A fetch rule with Below Class specified, fetches all matching information from occurrences of the target class (D) for all paths below the specified Below Class (A) to the target class, e.g. A-B1C1-D1, A-B1-C1-D2, A-B1-C2-D1, A-B1-C2-D2, A-B2-C1-D1, A-B2-C1D2, A-B2-C2-D1, A-B2-C2-D2.

To specify a Below Class:

1 Access the Fetch Rule form.

2 Click the Target tab. 3 Enter a target composite and class.

18-26

Using a Fetch Rule Fetching Information via All Paths to Target Class

4 Click Below Class in the Target category and select the class below which all paths to the target should be included in the fetch:

The fetch rule fetches information from all occurrences of Activity (the target class) accessed via all paths to Activity from Policy.

18-27

18

Using a Fetch Rule Fetching Information via All Paths to Target Class

18-28

Chapter 19 Using a FetchSQL Rule

A fetch rule can be used to retrieve data from an SQL table. The data values are added to the rule context. The fetchSQL rule is an extension of the fetch rule. See Chapter 18, Using a Fetch Rule.

19.1 Specifying a FetchSQL Rule

Use a fetch rule to retrieve data from an SQL database.

Placing the Symbol in the Rule Model

1 Via Modeler, access the rule model for the concept that requires the fetchSQL rule. 2 Select the ruleset in the rule model to which you want to attach the fetchSQL rule. 3 Click the Fetch button on the Modeler toolbar. The following menu is displayed:

19-1

19

Using a FetchSQL Rule Specifying a FetchSQL Rule

4 Choose FetchSQL. The Fetch SQL Rule dialog box is displayed:

5 Enter a name for the fetchSQL rule in the Name textbox. 6 Click OK. The rule symbol for the fetchSQL rule appears in the rule model:

19-2

Using a FetchSQL Rule Specifying a FetchSQL Rule

Accessing the Fetch SQL Rule Form

1 Select the fetchSQL rule symbol and click the Rule button on toolbar. The Fetch SQL Rule (200015) form is displayed:

2 Assign any rule options that you need.

Defining Error Handling

1 Select the Error Message tab. 2 In the Message field, enter the message that is displayed if the fetchSQL fails. If a fetchSQL rule fails and a message was not specified, Business Integrity Server displays a default message. If Warning is assigned to the rule, the error message is issued as a warning, and processing continues after the error message is issued.
19-3

19

Using a FetchSQL Rule Specifying a FetchSQL Rule

Add an asterisk (*) at the end of the message to display information about the work area that caused the error. Put the asterisk after an appropriate connecting word. Example: The following error message:

YOU CANNOT CLOSE * is displayed as:

ERR2404 YOU CANNOT CLOSE PROJECT "358"

Add two asterisks (**) at the end of the message to display the context of the target object whose location failed. Example: The following error message:

YOU CANNOT CLOSE ** is displayed as:

ERR2404 YOU CANNOT CLOSE PROJECT "358" ASSIGNMENT "1"

3 In the Erroneous Field textbox enter the number of the field on which the pointer should be positioned whenever the fetchSQL rule fails. The second textbox is the name of the field on which the pointer should be positioned. It is not necessary to enter the name. However, if the field name is unique, it is possible to identify the Erroneous Field only by its name.

If Warning is assigned to the fetch rule, entering an Erroneous Field is irrelevant. When a fetch rule that has been assigned Warning fails, the processing continues after the error message is issued as a warning

Viewing Triggering Objects

1 To view triggering objects for the rule, right-click in the Ruleset textbox and select Detail from the pop-up menu that is displayed. The Ruleset Review form is displayed. Right-click in the Ruleset No textbox and select Triggering Objects form the pop-up menu that is displayed:

19-4

Using a FetchSQL Rule Specifying a FetchSQL Rule

The triggering form displayed depends on the type of triggering object (i.e. concept, class, constructor). For a triggering concept the Triggering Concepts (200037) form is displayed:

Click the OtherTrigger button to view other triggering objects. The Rulesets: Triggering Objects form is displayed:

19-5

19

Using a FetchSQL Rule Specifying a FetchSQL Rule

2 To view the triggering fields, right-click with the pointer on a particular triggering object and select Fields from the pop-up menu that is displayed. The form displayed depends on the triggering object: For a concept: If the concept is Implemented the Design Fields (200027) form is displayed listing the triggering fields (otherwise, the Concept Fields form is displayed):

For a class: the Field in Class (200068) form is displayed listing the triggering fields For an operation: the Operation (200069) form is displayed listing the triggering fields. For programs/queries: the Program (200072) form is displayed listing the triggering fields.

19-6

Using a FetchSQL Rule Specifying a FetchSQL Rule

For a constructor: the Constructor Fields (2080) form is displayed listing the triggering fields. For an edit operation: the Oper Target Cls (200097) form is displayed listing the triggering fields. For a form: the Block Operation (200098) form is displayed listing the triggering fields.

Composing the Rule Text

1 Enter the text of the fetch SQL rule in the Rule Text field. See "FetchSQL Rule Syntax" on page 19-8.

Remember, all the fields referenced in an fetchSQL rule must be defined previously in the knowledgebase. To avoid ambiguities, a field referenced in the rule should be referenced by its number as well as by its name (e.g. FIELDA #3427)

An eMerge field name used in a fetchSQL rule can contain a blank. If any nested rulesets were specified in the rule model, the rule text is automatically inserted. (See "Automatic Rule Text" on page 19-10.) Rule Editor assists in composing the rule text (see Chapter 13, Rule Editor)unless the RULEEDITOR OFF command is issued. Any fields that are referred to in a rule must be accessible to the rule. See "Defining Rules for a Ruleset" on page 11-16 for more information. 2 Click the TempFields button to view the temporary fields currently defined in the knowledgebase.

3 Click OK.

Use the scroll bar to see all the lines of the Rule Text field.

Compiling the Rule

Click the Compile button to implement the rule (see Chapter 14, Implementation Stage of a Rule).

19-7

19

Using a FetchSQL Rule FetchSQL Rule Syntax

19.2 FetchSQL Rule Syntax

Following is the syntax for the fetchSQL rule statement:

DEFINE SQL <viewname> OPTIONS

The first statement in a fetchSQL rule. Defines the name of the view to be retrieved. The name assigned to the SQL data view to be retrieved. There is no significance to the order in which the options are specified. Each option is specified as KEYWORD=value. This cannot be split over more than one line. There must be no blanks before or after the equals sign (=). Options may be separated by one or more spaces.

CODE=

For operating systems in which the I/O module is generated in Assembler, this option specifies whether or not to generate code elements for the sub query.

19-8

Using a FetchSQL Rule FetchSQL Rule Syntax

YES NO

Generate code elements. By default, code elements are generated. Do not generate code elements.

This option is not relevant under HP-UX or i5/OS and it is ignored if provided. In these environments the I/O module is written in C which does not use code elements. SYNTAX= This option specifies how the <selectclause> of this DEFINE SQL statement is provided: SQL The <selectclause> is passed to SQL exactly as it appears in the DEFINE SQL statement, with no formatting performed by eMerge. This is the default, unless the eMergeSyntax option is assigned for the DBMS. OP The <selectclause> is provided in the old syntax, where eMerge must parse and format it before passing it to SQL. It is recommended that you switch over to the new system of specifying the <selectclause>. Future releases of eMerge will not necessarily support the old eMerge format. LDI= Specify the Logical DBMS ID for this <selectclause>. This points to the DBMS profile. To specify a Logical DBMS ID for the whole query, specify it in the Logical DBMS ID field in the Query Definition (100230) form. If a Logical DBMS ID is not specified, the default Logical DBMS ID defined for the database is used. If a default Logical DBMS ID is not specified, the Logical DBMS ID defined in the DBMS Profile Definition form is used. For an explanation of the Logical DBMS ID and the DBMS profile, see the DBMS Adapter Guide. CURSOR= <sqlselect statement> Indicates the type of SELECT. If the operation method is findByKey, then <cursornumber> is 0. Otherwise, <cursornumber> is 1. The second statement in a fetchSQL rule. Defines the SQL statement. The sqlselectstatement identifies the SQL table and data to be retrieved. The sqlselectstatement must start with the word SELECT and end with a semicolon (;). Only one such statement can appear in a fetchSQL rule. Introduces a fetchSQL rule which calls another ruleset. The USE keyword is optional, unless another ruleset is called as part of the statement or the THEN keyword is used. Introduces a repeated fetchSQL rule.
19-9

IF/USE

WHERE

19

Using a FetchSQL Rule FetchSQL Rule Syntax

<field1> <viewinputfield> IS INPUT FOR VIEW IS RETRIEVED THEN CALL <ruleset1> ELSE <ruleset2>

The field value assigned to the viewinputfield. The name of the field whose value is used to identify the SQL data retrieved. Assigns a value to the viewinputfield from field1. Specifies the name of the view to be retrieved. Fetches the view.
ELSE

Precedes the ruleset that is called if the fetchSQL is successful. If an clause is used, the THEN keyword must be used.

Calls the ruleset to be nested. The name (or number) of the ruleset to be called if the fetchSQL is successful. Precedes the ruleset that is called if the fetchSQL is unsuccessful. The name (or number) of the ruleset to be called if the fetchSQL is unsuccessful.

Example
In this example, the table myuser.tab3730 contains the columns lqa1 and
l1. DEFINE SQL fetch10-42 SELECT lqa1 FROM myuser.tab3730 WHERE l1 < @key-input1; IF VIEW fetch10-42 IS RETRIEVED THEN pack1 IS RETRIEVED FROM lqa1 AND STORED ELSE pack1 IS STORED AS 9.

Automatic Rule Text

Some of the rule text for nested rulesets is inserted automatically. If you have only specified a THEN ruleset in the rule model, the rule text entered for you in the Rule Text field has the following format:
THEN CALL ruleset_name #ruleset_no .
19-10

Using a FetchSQL Rule Retrieving SQL Data

If you have only specified an ELSE ruleset in the rule model, the rule text entered for you in the Rule Text field has the following format:
ELSE CALL ruleset_name #ruleset_no .

If you have specified a THEN ruleset and an ELSE ruleset in the rule model, the rule text entered for you in the Rule Text field has the following format:
THEN CALL ruleset_name #ruleset_no ELSE CALL ruleset_name #ruleset_no .

After you make any change to the text of a fetchSQL rule, the automatic ruleset text mechanism is disabled, and the rule text for nested rulesets must be entered manually.

Manipulating a Nested Ruleset

For information on how to manipulate a nested ruleset (e.g. add, copy, replace, reattach, deactivate, delete, or exclude) see Chapter 15, Working with the Rule Model.

19.3 Retrieving SQL Data

If you want to retrieve SQL values, use a fetchSQL rule. SQL data can be retrieved and used in subsequent rules or stored in the triggering object.

DEFINE and SELECT Statements

The first statement in the fetchSQL rule is the DEFINE statement. It is followed by the SELECT statement. The SELECT statement must be terminated with a semicolon. Only one SELECT statement can appear in a fetchSQL rule. The SELECT statement can contain other SELECT statements. The DEFINE and SELECT statements need only appear once in one of the fetchSQL rules defined. Other fetchSQL rules can then be written without these statements.

If DEFINE and SELECT statements are defined, but a particular fetchSQL rule does not contain such statements, and the SQL table referenced changed, a warning is issued indicating that the rules must be recompiled.

19-11

19

Using a FetchSQL Rule Retrieving SQL Data

Fields Used by a FetchSQL Rule

All fields used in a fetchSQL rule must be previously defined somewhere in the knowledgebase. Field names and field synonyms that are referenced in a fetchSQL rule must be unique in the knowledgebase. In addition, the column in the SQL table referenced must exist. If an ambiguous field name, field synonym or a non-existent SQL table column is referenced, an error is issued.

Tables

For information on synonyms see "Using Synonyms" on page 5-5. You can keep the automatically defined synonym unique by not defining your synonyms or naming objects with the automatic synonym naming convention.

Example
The following five SQL tables exist. SQL Table Name Table1 Table2 Table3 Table4 Table5 Fields FieldA FieldB FieldC FieldD FieldE SQL Column Name

The following fields and their synonyms are defined in the knowledgebase: Field Number 101 102 103 104 105 106 107 108 FieldA FieldB FieldC FieldD FieldK FieldH FieldA FieldJ FieldE FieldB FieldE Field Name Field Synonym

19-12

Using a FetchSQL Rule Retrieving SQL Data

Selections and results

Some examples of SQL selections and their results are shown below:

SQL Selection
FIELDC FROM TABLE3 FIELDC FROM TABLE1

Result field #103 selected SQl error

Reason For Error/Correction no column named FieldC in Table1 no column named FieldJ in Table3 FieldA is not unique. Give FieldA a unique synonym (e.g. FieldASyn). Select FieldC as FieldASyn from Table1. Field #101 is selected. FieldB is not unique, it is a field name and a field synonym

FIELDJ AS FIELDC FROM TABLE3 SQl error FIELDC AS FIELDA FROM TABLE3 error

FIELDB FROM TABLE2

error

FIELDE AS FIELDD FROM TABLE5 field #104 selected data from FieldE is stored in FieldD FIELDB AS FIELDC FROM TABLE2 field #103 selected data from FieldB is stored in FieldC FIELDA FROM TABLE1

error

FieldA is not unique. Give FieldA a unique synonym (e.g. FieldASyn). Select FieldA as FieldASyn from Table1. Field #101 is selected

FIELDA AS FIELDC FROM TABLE1 field #103 selected FIELDD AS FIELDJ FROM TABLE4 field #108 selected

Example
To fetch data from an SQL table and put the data into the rule context, use a fetch rule like the following:
define sql FETCH-SQL-DATA select K2 as NUM4, Namne35 from ZSRENA.TAB35 where K2=@FSSMALLINT; VIEW fetch-sql-data IS FETCHED 14 is input for FSSMALLINT CHAR4 is get from NAME35 and stored.

Note: a value must be assigned to the field fssmallint. This is accomplished using the keywords, IS INPUT FOR. (This is similar to using the IS TARGETKEY keywords in a fetch rule.)

19-13

19

Using a FetchSQL Rule Continuing Processing After a FetchSQL Fails

19.4 Continuing Processing After a FetchSQL Fails

If the target does not exist, you can prevent an error occurring and allow processing to continue by assigning one or more of the following options from the Fetch SQL Rule (200015) form: Warning Processing continues and the error message defined for the rule (or the default eMerge error message if an error message is not defined) is displayed as a warning and not as an error. IgnoreMissingTarget (Target Access category) Processing continues even if no rows from the SQL table were retrieved (and no subsequent call rule exists within the ruleset). IgnoreNew (Target Access category) The target corresponding to the new values (the values after the update) is never fetched. IgnoreNew is useful with fetchSQL rules for efficiency purposes and it should be specified when possible. IgnoreOld (Target Access category) The target corresponding to the old values (the values before the update) is never fetched. IgnoreOld is useful with fetchSQL rules for efficiency purposes and it should be specified when possible.

When processing continues, any fields that the fetch rule would have added to the rule context are not added.

19.5 Listing Rules Using the Same SQL View

Sometimes it is necessary to obtain a list of all rules that use the same SQL view. Example: Several fetchSQL rules use the same SELECT statement. The rules are not necessarily in the same ruleset. If a change is made to the SELECT statement or if a change is made to the SQL table referenced, all the rules that use the SELECT statement may have to be recompiled.

When compiling the rule in which the SELECT statement is defined, a Warning is issued indicating that other rules using this SELECT statement must be checked.

To list all rules using the same SELECT statement:

1 Access the fetchSQL rule definition form for the particular rule. 2 Right-click in the Rule textbox. Select Rules useTarget SQL View from the pop-up menu that is displayed:

19-14

Using a FetchSQL Rule Replacing Strings in an SQL View Statement

The Referring Rules to Target SQL View (782) form is displayed, listing all the rules that use the SELECT statement referenced in the current fetchSQL rule:

19.6 Replacing Strings in an SQL View Statement

Strings appearing in an SQL View statement can be replaced dynamically at runtime. A String Replacement table is built that contains the mapping between source strings and their replacement target strings. In the SQL View statement itself the source string to be replaced is enclosed within a replacement deliminator ([ ])

19-15

19

Using a FetchSQL Rule Replacing Strings in an SQL View Statement

The source string can be split between two lines: e.g. xxx [yy zz] ....

At runtime, the SQL View statement is parsed, and for any strings within a replacement deliminator, a look-up is performed in the String Replacement table. If the source string is found in the table, it is replaced by its replacement target string. If the source string is not found in the table, an error message is issued.

To specify a replacement string:

1 Access the SQL DBMS Definition (23407) form:

2 Click ReplaceString. The SQL Replace String (23434) form is displayed:

19-16

Using a FetchSQL Rule Replacing Strings in an SQL View Statement

3 In the Source String textbox enter the name of the string to be replaced. The source string can be any string containing alfanumeric, as well as special characters (e.g. blank, minus, slash, back slash, dot , underline, etc). It is non-case sensitive string up to 32 characters in length. The following synonym strings are reserved and cannot be used for a source string value on the SQL Replace String (24434) form (nevertheless, they can be used in an SQL View statement as synonyms for TABLECREATOR and TABLE-LOCATION respectively): TABLECREATOR Synonyms TABLELOCATION Synonyms TAB CRT, TAB-CRT, TAB_CRT, CRT TAB, CRT-TAB, CRT_CRT,CREATOR TABLE, CREATOR-TABLE, CREATOR_TABLE, TABLE CREATOR, TABLE_CREATOR TAB LOC, TAB-LOC, TAB_LOC,LOC TAB LOC-TAB, LOC_TAB,LOCATION TABLE, LOCATION_TABLE, LOCATION_TABLE,TABLE LOCATION< TABLE_LOCATION If TABLE-CREATOR is specified for the source string, then the following applies: If a target string is specified, then it is used. If a target string is not specified, then the string value specified for the SQL Class Table Creator field on the SQL DBMS Details (23408) form is automatically used for the target string. If TABLE-LOCATION is specified for the source string, then the following applies: If a target string is specified, then it is used.

19-17

19

Using a FetchSQL Rule Handling SQL Multi-Platform Syntax Issues

If a target string is not specified, then the string value specified for the SQL Class Table Location field on the SQL DBMS Details (23408) form is automatically used for the target string.

4 In the Target String textbox enter the name of the replacement string. The target string can be an empty string. 5 Select a replace rule from the Replace Rule drop-down listbox. The replace rule determines how replacement is performed. AsIsThe target string replaces the source string as is without any additions. Table CreatorThe source string is replaced as follows: For SQL DBMS type ORACLE and DB2, a dot (.) character is added after the target string. For SQL DBMS type i5/OS/DB2, a dot (.) character (or slash (/) character if SYS-SQL is option is assigned in the Adapter Profile) is added after the target string. Table LocationThe source string is replaced as follows: For SQL DBMS type DB2 (not i5/OS), a dot (.) character is added after the target string. For SQL DBMS type ORACLE, an at (@) character is added after the target string. Part of ConstantThe source string is replaced as follows: If the character before or after the source string is a single or double quotation mark, then the target string replaces the source string with the quotation marks adjacent to the target string removed. Example: Source string is: "abc" [t1] "def". Replacement target string is: kk. The resulting string after replacement is: "abc kk def". The following applies: If the value TABLE-CREATOR is used for the source string, then Table Creator must be selected for Replace Rule. If the value TABLE-LOCATION is used for the source string, then Table Location must be selected for Replace Rule. 6 Assign any options that are required to control the replacement behaviour. 7 Click OK

19.7 Handling SQL Multi-Platform Syntax Issues

In a multi-platform environment, when developing SQL based applications, issues arise from differences in the SQL syntax between the
19-18

Using a FetchSQL Rule Handling SQL Multi-Platform Syntax Issues

platforms. In such cases, use directives in fetchSQL statements and in SQL query statements to avoid compilation problems with SQL formulas. A directive (i.e. a string starting with a percent sign (%)) instructs the system to compile the appropriate SQL statement that is specific to the particular running environment (see "Directives" below).

When the eMerge Syntax option is assigned via the DBMS definition form, an OPTIONS SYNTAX=SQL clause must be implicitly used in a fetchSQL rule and in an SQL query.

The following examples illustrate some of these issues: Example:

TRANSLATE

The DB2 DIGITS function is not supported in Oracle. The function gives a similar result to the DB2 DIGITS function.

... %DB2 DIGITS(T4.COV_PROP_SEQ) %ORA TRANSLATE(TO_CHAR(T4.COV_PROP_SEQ,00000), %ORA 012345789-+.,,0123456789)

It is the users responsibility to determine the number of digits before and after the decimal point.

Example: DB2 arithmetic operations with date and time type are different in Oracle:

INTERVAL data type is used to specify a number of days/months/years.

... %DB2 AND (LOSS_DATE + 4 YEARS) <= :EFFECTIVE-DATE %ORA AND (LOSS_DATE + INTERVAL 4 YEAR) <= :EFFECTIVE-DATE ; ...

NUMTOYMINTERVAL(<Number-of-Years>,YEAR) is used to convert months/years to date format.

... %DB2 %DB2 %ORA %ORA ... %DB2 %DB2 %ORA %ORA ; ...

date(cast(:tmp-c-10 as char(10))) + pol_term_cd years cast(cast(:tmp-c-10 as char(10)) as date) + NUMTOYMINTERVAL(POL_TERM_CD,YEAR) else else date(cast(:tmp-c-10 as char(10))) + pol_term_cd month cast(cast(:tmp-c-10 as char(10)) as date) + NUMTOYMINTERVAL(POL_TERM_CD,MONTH)

19-19

19

Using a FetchSQL Rule Handling SQL Multi-Platform Syntax Issues

Example: The Fetch first row feature is not supported by Oracle. To get the first row in Oracle, the original SELECT statement must be included within the following SELECT statement:
SELECT * from (<original select statement>) where ROWNUM=1 ... SELECT %ORA * FROM (SELECT CHG_POL_PREM_AMT, CANC_REINST_FTR FROM POLICY_ENDRSMNT WHERE POL_SYMBOL = :F7700 ... ORDER BY PROCESS_DATE DESC, PROCESS_TIME DESC %ORA ) WHERE ROWNUM = 1 %DB2 fetch first row only ;

Directives
The following is a list of supported directives: Directive %ORA %ORACLE %ORA-UNIX %ORACLE-UNIX %ORA-LINUX %ORACLE-LINUX %ORA-HPUX %ORACLE-HPUX %DB2-ISERIES %DB2-Z/OS %DB2-VM The following applies when using directives: A directive must start at the very beginning of a rule or query statement line. A rule or query statement that contains a directive cannot have a semicolon (;) that is used as an end-of-statement as part of the statement line.
19-20

Using a FetchSQL Rule Handling SQL Multi-Platform Syntax Issues

%ORA and %ORACLE are synonyms. %ORA is a directive that can be used in place of the Oracle directives %ORA-HPUX and %ORA-LINUX and %ORA-UNIX. %DB2 is a directive that can be used in place of the DB2 directives %DB2-ISERIES and %DB2-VM and %DB2-Z/OS. When there is a difference between the platforms, then a platform specific directive must be used.

19-21

19

Using a FetchSQL Rule Handling SQL Multi-Platform Syntax Issues

19-22

Chapter 20 Using a Call Rule

A call rule is used for the following:

To group common processing together in a single module for use by a number of rulesets. To group together a specific set of rules that are only to be executed conditionally. To run a COBOL or PL/I program, within the rules environment.

Calls are used to branch to another ruleset or to an external program. Any field values added to the rule context via a called (i.e. a nested) ruleset remain in the rule context when returning to the rule that initiated the branch (i.e. to the calling ruleset). A ruleset can also be called directly from a fetch rule. A fetch rule calls another ruleset in the following circumstances:

When different processing must continue dependent on whether the target constructor exists. When a group of target constructor occurrences is fetched, and processing must be done for each occurrence. For details and an example refer to "Retrieving a Group of Target Occurrences" on page 18-15.

20.1 Specifying a Call Rule

Use a call rule to branch to another ruleset. When you incorporate a call in a ruleset, the ruleset being called is referred to as a nested ruleset. 1 From the rule model, select the ruleset to which the call rule is to be attached. 2 Click the Call Rule button on the toolbar. 3 Fill in the Call rule dialog box. Fill in the rule name in the Name textbox and the Nested Ruleset in the Then and/or Else textboxes. If you do not enter a Then ruleset the Then symbol connected to the rule will appear

20-1

20

Using a Call Rule Specifying a Call Rule

empty in the rule model and you are not able to compile the rule text for the call rule until you define at least a Then ruleset. 4 Access the Call Rule form to define the call rule:

5 Assign any rule options that you need. 6 Compose the rule. Nested rulesets specified via Then, Else, or Then-Else textboxes, have rule text automatically inserted. See "Automatic Rule Text" on page 20-4. Modify the text of the call rule as needed in the Rule Text field. Enter the rule text as described in "Call Rule Syntax" on page 20-3. Rule Editor assists in composing the rule text (see Chapter 13, Rule Editor)unless the RULEEDITOR OFF command is issued. See "The Rule Context" on page 11-19 for more information. 7 Click Apply.
20-2

Using a Call Rule Call Rule Syntax

8 Click Compile to implement the rule.

20.2 Call Rule Syntax

Following is the syntax for the call rule statement. Refer to "Making a Rule Conditional" on page 12-4" for the syntax of the conditional call rule.

WHILE

Introduces a repeated call rule. The call clause (after the expression) is repeated for as long as the condition contained in the WHILE clause is valid. The name of the field used as a comparison in the WHILE clause. If no association is specified in the WHILE clause (EQ, NE etc.), EQ is assumed. A numeric or character expression comprising values (numbers, character strings or dates), fields and operators (+-*/):

<field> <expression>

A field can be from the triggering object, from a computed field from another rule, or from a global field (e.g. CURRENT-OPER). (See page 11-19

20-3

20

Using a Call Rule Call Rule Syntax

for information about global fields). If no relationship is specified (EQ, NE etc.), EQ is assumed. <rulesetname> <rulesetno> The name of the ruleset to be invoked. If the ruleset name is not unique, use the ruleset number (immediately preceded by the # symbol).

Example
call calc-discount.

Automatic Rule Text

Below is a sample of the rule text for nested rulesets that is inserted automatically. If you have only specified a Then ruleset in the rule model, the rule text entered for you in the Rule Text fields has the following format. In this case the rule is ready to be compiled, and you may do it directly from the model.
CALL ruleset_name #ruleset_no .

If you have specified a Then ruleset and an Else ruleset in the rule model, the rule text entered for you in the Rule Text fields has the following format:
IF THEN CALL ruleset_name #ruleset_no ELSE CALL ruleset_name #ruleset_no .

After you make any change to the text of a call rule, the automatic ruleset text mechanism is disabled, and the rule text for nested rulesets must be entered manually.

Manipulating a Nested Ruleset

For information on how to manipulate a nested ruleset (e.g. add, copy, replace, reattach, deactivate, delete, or exclude) see Chapter 15, Working with the Rule Model.

20-4

Using a Call Rule Other Methods to Create a Call Rule

20.3 Other Methods to Create a Call Rule

You can create a call rule via the Call Rule form; however, the rule will not appear in the rule model. It is recommended that you define rules only via the rule model (i.e. via a concept). Access the Call Rule (100777) form and assign the CreateThen option to the call before compiling the rule. On compilation, the nested ruleset is automatically defined. If you assign the CreateThen option, and/or the CreateElse option (see "Calling a Ruleset Conditionally" on page 20-6), you must identify the nested ruleset in the rule by a name (and not by a number). The name must be unique. (As with any ruleset name, the name can be up to 16 characters, consisting of letters, digits, blanks and any of: - _ " . and #.) Example: To call a ruleset that is currently undefined and have it automatically defined. Use a call like the following:

After compiling the Call rule, the ruleset (RULESET10) is created and the option (CreateThen) is unassigned. (This prevents another ruleset being created if the rule is recompiled.)

20-5

20

Using a Call Rule Calling a Ruleset Conditionally

The new ruleset can be accessed by right-clicking in the Ruleset textbox and selecting Detail from the pop-up menu that is displayed. The Ruleset Review form is displayed:

Click the ThenRuleset button to access the new ruleset.

If you delete the call, since the nested ruleset exists in its own right, the nested ruleset is not deleted. If the nested ruleset is no longer required you can delete it as you would delete any ruleset (see "Deleting a Ruleset or Rule" on page 15-7).

20.4 Calling a Ruleset Conditionally

The same conditions that apply to calling a ruleset unconditionally also apply to calling a ruleset conditionally. Example: To call a ruleset dependent on whether a condition is met. Use a call like the following:
If FIELDA = CURRENT-DATE then call RULESET10 else call RULESET11.

Assign the CreateThen option to automatically define the Then ruleset. If the condition includes an Else clause, assign the CreateElse option to

20-6

Using a Call Rule Calculating a Value Dependent on the Operation Code

automatically define the Else ruleset. Access the Then ruleset via the ThenRuleset button and the Else ruleset via the ElseRuleset button.

If the condition only has one side to it (i.e. there is no else clause), you can use the WHEN keyword. Refer to the full syntax for the call in the General Reference.

Repeating a Call Conditionally

Use the WHILE keyword to create a call to a ruleset that is repeated until a condition is met. Example: To call a ruleset repetitively until a condition is met. Use a call like the following:
while FIELDA lt 1000 call RULESET14.

Upon compilation this rule is flagged automatically as a conditionally repeated call if the rule includes the WHILE keyword.

20.5 Calculating a Value Dependent on the Operation Code

By assigning options you can change the default that causes a rule to be triggered. Refer to"Validating a Field Dependent on the Operation Code" on page 17-9 for an example of assigning the OnDelete option. Refer to the Form Reference for details of the options.

20.6 Calling a Program

Integrate programs (e.g. COBOL or DBCOBOL programs) within rules when you want to perform operations that can be done more easily via a program (e.g. accessing a non-eMerge database to retrieve a value).

A program called by a call cannot access an eMerge database or a datasource. Therefore, the program cannot include the following statements which access the database: INSERT, DELETE, CHANGE, SEND OPERATION, SEND LINE.

The program parameters are rule context independent. These parameters are assigned from the rule context when the program is invoked. Returned values are added to the rule context, or replace values in the rule context.

20-7

20

Using a Call Rule Calling a Program

To call a program, define the following:

The program to be called. The definition of the program, with any parameters that are passed to it, to run under the BLP. This definition is done in the Program Definition form. The call that includes any parameter values that must be passed to the program, or received back from the program The nested ruleset that calls the program directly (instead of rules). This ruleset can be defined automatically by the call or it can be defined automatically when the program is defined in the Program Definition (100801) form.

The nested rule (A) in the ruleset (A) calls a ruleset (B) which calls the program. In addition, the rule passes parameters to the program and receives values back from the program. The nested ruleset (B) can be defined via the call or via the program definition in the BLP.

20-8

Using a Call Rule Calling a Program

Define the Program

1 Access the Program Definition form:

2 Define the program to run under the BLP by entering the following: Program No. A number that uniquely identifies the program. The number should reflect the ruleset that is connected to via the first four digits.

A program cannot be defined with the same number as an existing query.

Program ID The name of the program. The name can be up to eight characters, consisting of letters, digits, blanks and any of: - _ ' " . and #. The Program ID must be identical to the executable module name of the program. In DBCOBOL it must be identical to the SAP-PROGRAM-ID assigned in the program.
20-9

20

Using a Call Rule Calling a Program

CICS

If the program is to be run in batch and online under CICS, two separate versions of the program are required, if calls to the operating system or CICS are made within the program. Unless different module libraries are used for CICS and non-CICS, both the regular version program ID and the CICS version program ID must be entered in the Program Definition (100801) form in the Program ID and Program CICS ID fields respectively. The default value for the Program CICS ID field is the Program ID field value. Name The name for the program. A longer name is used for extra clarity about the program. The name can be up to 16 characters, consisting of letters, digits, blanks and any of: - _ ' " . and #.

If the ruleset does not exist, it is automatically created using this name as the ruleset name.

Language

The language that the program is written in.

Define Fields
Define any fields that are to be passed to the program in the Fields groupbox and that are to be returned from the program. Assign the Return option (Parameters tab > Role category) to all the fields that will receive a value to be returned from the program (the RETURNING keyword is used for the field in the call rule text):

Specify the Ruleset Number

Via the Ruleset tab, specify a number for the ruleset that calls the program. This ruleset is the one called by the call.

20-10

Using a Call Rule Calling a Program

Example
The COBOL1 program was defined to be called by the Call Program ruleset. Two fields are passed to the program and two are returned from the program (identified by the Return option).

View the ruleset definition in the Ruleset Review form:

A ruleset calls the COBOL1 ruleset, passing the values of the Birth Date and Start Employment fields. Two values are returned by the program1, Pension Rate and Retire Benefit. Use a call like the following:
20-11

20

Using a Call Rule Calling a Program

call COBOL1 #340012 using BIRTH-DATE, START-EMPLOYMENT returning PENSION-RATE, RETIRE-BENEFITS.

The returned values do not have to be passed to temporary fields.

20-12

Chapter 21 Using a Derivation Rule

A derivation rule is used to: update a target concept, composite/class, or a constructor The target to be updated can be specified via: rule definition form See "Specifying a Derivation Rule" on page 21-2. rule syntax See "Target Specification via Derivation Rule Syntax" on page 21-19 and "Specifying an Operation as the Target for a Derivation Rule" on page 21-20.

invoke an operation See "Invoking an Operation via a Derivation Rule" on page 24.

Updating a target occurrence can result in operations being sent to other object occurrences in order to update their occurrences. When the target object is updated the derivation rule is executed and a message is sent to the target object. Updating the target object, in turn, triggers all the rulesets attached to the target object. Any derivation rules in these rulesets send operations to other objects and so on. A derivation rule can only be used in a ruleset attached to a concept, class, or a constructor.

When defining derivation rules for an object, only consider target objects that are directly affected by the derivation. You do not need to consider any other target objects. eMerge controls the derivation chain so that looping (e.g. target object 4 deriving to target object 1) does not occur unless specifically requested. For details of looping and recursion see Chapter 27, Looping and Recursion.

21-1

21

Using a Derivation Rule Specifying a Derivation Rule

A derivation rule is only triggered for an operation that has no target. However, an immediate derivation is also triggered for an operation that has a target.

21.1 Specifying a Derivation Rule

Use a derivation rule to update data in the database that is not currently available. From the rule model, access the Derivation Rule form to define the derivation rule. The target tab lists target information depending on the type of the target objecte.g. concept, class in a composite, or constructor. If the target object is a concept, the Derivation Rule (200007) form is displayed:

If the target is a class in a composite or a constructor, the parallel Derivation Rule (200033) form is displayed:

21-2

Using a Derivation Rule Specifying a Derivation Rule

When a class is used as a target in a derivation rule under an operation, the source operation, the ruleset and the rule numbers are derived to the class.

1 Assign any rule options that you need. 2 To view target fields, click the TargetField button (Target tab). When in the Analysis or Design stages, the Concept Fields form is accessed. When in the Implementation stage, the Design Fields form is accessed:

3 To view triggering objects for the rule, right-click in the Ruleset textbox and select Detail from the pop-up menu that is displayed. The Ruleset

21-3

21

Using a Derivation Rule Specifying a Derivation Rule

Review form is displayed. Right-click in the Ruleset No textbox and select Triggering Objects form the pop-up menu that is displayed:

If the triggering object is a concept the Triggering Concepts (200037) form is displayed:

4 To view the triggering fields for the concept, right-click in the concept textbox and select Fields form the pop-up menu that is displayed. When in the Analysis or Design stages, the Concept Fields form is accessed. When in the Implementation stage, the Design Fields form is accessed.

21-4

Using a Derivation Rule Specifying a Derivation Rule

To view triggering fields for other triggering objects, click the OtherTrigger button to access the Rulesets: Triggering Objects (200051) form:

5 Compose the rule. Enter the text of the derivation rule in the Rule Text text box of the Derivation Rule form. See "Derivation Rule Syntax" on page 21-6. Rule Editor assists in composing the rule text (see Chapter 13, Rule Editor)unless the RULEEDITOR OFF command is issued. To avoid ambiguities, a field referenced in the rule text should be referenced by its number as well as by its name (e.g. FIELDA #3427)

Click the TargetField button to see the fields that are part of the target object.

Any fields that are referred to in a rule must be accessible to the rule. See "The Rule Context" on page 11-19 for more information. If you require a list of existing temporary/global fields that are defined in the knowledgebase, click the TempFields button (see "Listing Temporary Fields" on page 12-7). 6 Click Apply. 7 Click the Compile button to implement the rule.

21-5

21

Using a Derivation Rule Derivation Rule Syntax

21.2 Derivation Rule Syntax

Following is the syntax for the derivation rule statement. Refer to "Making a Rule Conditional" on page 12-4 for the syntax of the conditional derivation rule.

<field1>

The name of the field used to identify the target data object; either as a path field to the target data object (using the PATH keyword) or as the key field of the target data object (using the TARGETKEY keyword). The entire path and/or key must be specified. The name of the field to be written (derived) to the target data object. The field value in the rule context overwrites the field value in the target data object. Refer to "The Rule Context" on page 11-19. The field value in the rule context is added to the field value in the target data object. Refer to "The Rule Context" on page 11-19. The field value in the rule context is subtracted from the field value in the target data object. Refer to "The Rule Context" on page 11-19. The occurrence whose key value is listed here, <field2>, is copied to a new occurrence whose key value is the value of the field listed, <field1>, using the keyword TARGETKEY. If the data object being copied has dependents, all the dependents are also copied. Refer "Copying an Occurrence" on page 21-18. The name of the field in the target data object.

<field2> MOVED ADDED SUBTRACTED USED AS FROMKEY

<field3>

Example
item-no is targetkey quantity is subtracted from quantity-on-hand.
21-6

Using a Derivation Rule Writing to a Target Object Occurrence

21.3 Writing to a Target Object Occurrence

There are a number of different ways to write to another target object:

Writing to a parent target object occurrence Writing a new target object occurrence Writing to an existing target object occurrence Automatically generating a parent target object occurrence

21.4 Writing to a Parent Target Object Occurrence

The simplest case of a derivation is a single update of a field in the parent target object. The value of a field in a dependent object can be either added to a value in the parent object, or the value in the parent object can be overwritten with the value in the dependent object:

Use a parent derivation to add or move a field value from a field in a dependent object occurrence to a field in a parent object occurrence.

Defining a Parent Derivation

1 From the concept model, select the dependent concept to which you want to attach a ruleset.

21-7

21

Using a Derivation Rule Writing to a Parent Target Object Occurrence

2 Choose Object Concept Design. The Concept: Design (2013) form is accessed. Right-click in the Design textbox and select Class from the popup menu that is displayed:

The Constructor: Class Definition (100217) form is displayed. 3 Right-click on the field whose value you wish to derive to the parent concept. Select Advanced > Parent Derivation from the pop-up menu:

21-8

Using a Derivation Rule Writing to a Parent Target Object Occurrence

The Parent Derivation (100213) form is accessed:

4 Enter the number of the composite in the Composite No. field, the number of the parent class in the Parent Class field and the number of the target field to be updated in the Target Field field. Together these fields identify the target for the derivation. 5 Assign the type of update: Add to the target field or Move the value to the target field. The default is that the value is moved to the target field.

As with all derivations, the update to the parent object will trigger any parent derivations defined for that object.

Example
An object hierarchy consists of the Order object and its dependent Item object. To see the total price for an order each time a quantity of an item is added to the order, the value of the Item Price field (representing the total price for the item) is derived from the dependent Item object to the parent Order object using a derivation rule. The Item Price itself is calculated via a computation rule, locally in the Item concept, using the value of the Unit Price (for the item) multiplied by the value of the Quantity Ordered.

21-9

21

Using a Derivation Rule Writing a New Target Object Occurrence

Select the Item concept from the rule model and repeat steps 1to 3. The derivation from the Item Price field in Item to the Order Price field (target field # 3505) in Order is defined:

When defining a parent derivation you must know the class and composite numbers as well as the field numbers involved. The field numbers are available via Concept: Design form. The class number is shown in the Constructor: Class Definition (100217) form. The composite number is usually the first two digits of the class number. It can be verified from the Concept: Design form via the Composite button.

Every time an item is added to the list of items ordered, the value of the Order Price field in Order is updated to reflect the current sum of all the item prices for all the items ordered, i.e. the value calculated for Item Price (based on the Unit Price and Quantity Ordered for an item) is added to the Order Price.

21.5 Writing a New Target Object Occurrence

A default derivation rule is used to create a new target object occurrence based on data in the triggering object. A default derivation is one where options such as Secondary or SameComposite are not assigned for the derivation. See "Writing to a Target Occurrence in the Same Target Hierarchy" on page 21-12. The new target object occurrence can be either an independent or dependent target object occurrence.

21-10

Using a Derivation Rule Writing a New Target Object Occurrence

Writing to an Independent Target Object Occurrence

Example: When a new employee is entered to the application for the first time, a new salary file must be opened:

A derivation rule is defined to create a new Salary occurrence, where all confidential data is stored (e.g. salary, management comments).

If an employee leaves the company the same derivation rule is used to remove the salary details.

Use a derivation rule like the following:

FIELDZ is targetkey.

Fieldz, is the key field in the target object and exists in the triggering object. A new target object occurrence with the triggering object value for Fieldz is created. Compare the rule text with the rule text for the fetch rule on page 18-1. The rule type (fetch or derivation) specifies whether information is fetched from, or written to, the target object. The key field (Fieldz in the example) is automatically written to the new occurrence. If additional fields from the triggering object are required in the target object, they are explicitly written to the target object as part of the derivation rule:
FIELDZ is targetkey FIELDA is moved FIELDB is moved to FIELDB1.

Fielda is defined both in the triggering object and in the target object. Fieldb is mapped to another field in the target object (Fieldb1).

21-11

21

Using a Derivation Rule Writing a New Target Object Occurrence

Writing to a Dependent Target Object Occurrence

If the target object is a dependent object, the derivation rule must include the path fields needed to access the target object.

The path fields must be available in the rule context for the triggering object.

Example: When a new employee is entered to the application, a new occurrence must be added to the Department hierarchy, listing the employees in the department. Use a derivation rule like the following:

FIELDY is path FIELDZ is targetkey.

If a necessary path field is not specified an error message is returned.

Writing to a Target Occurrence in the Same Target Hierarchy

If the target occurrence is an occurrence in the same target hierarchy as the triggering object occurrence, the derivation rule must include this information. The information is included by assigning an option as part of the definition of the derivation rule.

21-12

Using a Derivation Rule Writing a New Target Object Occurrence

The target object can be in the same branch of the same target object hierarchy occurrence. For example:

The target object can also be in a different branch of the same target object hierarchy occurrence. For example:

If the derivation is from a dependent object occurrence to a parent object occurrence, use a parent derivation. See "Writing to a Parent Target Object Occurrence" on page 21-7.

To specify that the target is in the same branch in the same object hierarchy, assign the SameBranch option (Target tab > Memory category).

21-13

21

Using a Derivation Rule Writing to an Existing Target Occurrence

If you have a derivation to an object in the same branch, in an object hierarchy occurrence, and you do not assign either the SameBranch or SameComposite option, you receive an error. You can assign the SameComposite option instead of the SameBranch option without receiving an error. However, this is less efficient. To specify that the target is in different branch in the same object hierarchy, assign the SameComposite option (Target tab > Memory category). If you do assign the SameComposite option for a derivation to an object in the same object hierarchy occurrence you do not receive an error. However, this is less efficient.

21.6 Writing to an Existing Target Occurrence

The derivation rule is used to update another object occurrence in the database. The default situation is that a new object occurrence is created by the derivation rule. If an occurrence already exists an error message is returned when the derivation attempts to write a new occurrence.

The Occurrence Definitely Exists

To write to an existing object occurrence assign the Secondary option (Target tab > On Operation category) to the target object options for the derivation. Example: When a new employee is entered into the application for the first time, the department number for the employee is allocated. The Department object must also be updated to reflect the number of employees in the department.

A derivation rule is defined to update the existing department by incrementing the value in the counter field by one.

21-14

If an employee changes departments, or leaves the company the same derivation rule is used to recalculate the number of employees in each department.

Using a Derivation Rule Generating a Parent Occurrence Automatically

Use a derivation rule like the following:

FIELDZ is targetkey 1 is added to FIELDA.

The Secondary option was assigned to the derivation.

The Occurrence Might Exist

If a derivation is to a target occurrence that might exist, assigning the Secondary option results in an error when the target occurrence does not exist. However, not assigning an option results in the derivation failing when the target occurrence does exist. To prevent this problem, assign the InsertEqualChange option (Target tab > On Operation category) instead of the Secondary option: If the target occurrence does not exist, the derivation is treated as normal, and a new occurrence is created. If the target occurrence does exist, the operation is considered to be a change operation (even though the operation code is insert), and the derivation updates the existing occurrence.

21.7 Generating a Parent Occurrence Automatically

A derivation to a dependent occurrence requires that the parent occurrence exists. To access the dependent occurrence the key fields of the parent occurrence must be known (the path fields). If the parent occurrence does not exist, assigning the Auto option on the class for the object, results in the parent occurrence automatically being generated whenever a dependent occurrence is created for which the parent does not exist.

21-15

21

Using a Derivation Rule Generating a Parent Occurrence Automatically

To generate a parent occurrence automatically:

1 From the model, double-click the concept for which you want an occurrence automatically generated. The Concept form is displayed.

2 Right-click in the Concept textbox and select Main Design from the popup menu that is displayed. The Concept: Design (2013) form is displayed.

3 Right-click in the Design textbox and select Composite form the pop-up menu that is displayed. The Composite Definition (100301) form is displayed:

21-16

Using a Derivation Rule Ignoring a Missing Target Occurrence

4 Select the class for which you want the occurrence automatically generated and assign the Auto option (General category).

If the object is an independent object, and its key field is assigned the Entity option, the automatic generation of the parent object, on deriving a dependent object occurrence, fails. The check to insure referential integrity between the triggering object and the parent object is done via the Entity option, before processing the derivation to the dependent object which triggers the automatic generation of the parent.

21.8 Ignoring a Missing Target Occurrence

If the target occurrence does not exist, or an occurrence in the path does not exist and the Auto option is not assigned (see above), an error occurs. To prevent the error occurring and to allow processing to continue assign the IgnoreMissingTarget (Target tab > Access category) and, if relevant, the IgnoreMissingPath (Target tab > Access category) options in the derivation definition: The IgnoreMissingTarget option results in an attempt to access an occurrence, that does not exist, being ignored. The IgnoreMissingPath option results in an attempt to access an occurrence in the path to the target, that does not exist, being ignored.

21-17

21

Using a Derivation Rule Copying an Occurrence

21.9 Copying an Occurrence

A new occurrence of a target concept, based on an existing occurrence, can be created with a derivation rule using the keyword USED AS
FROMKEY.

Example: A new order is required that is similar to an existing order; therefore, a new occurrence of the existing Order must be inserted:

The key field of the existing Order concept is Order ID. New Order ID has the value of the key for the new Order being inserted. The value CopyOrder is the key value of the existing order from where the data is copied. The result is that a new occurrence of Order is inserted having a key value of New Order ID and containing the data from the existing Order.
New Order ID IS TARGETKEY FOR Order ID CopyOrder IS MOVED TO Order ID USED AS FROMKEY.

If the target concept occurrence has dependents, all the dependent occurrences are also copied. This is a powerful method to copy hierarchal information via a derivation rule.

On delete, the rule statement with the keyword USED AS FROMKEY is ignored. On change, the New Order ID and CopyOrder fields must be temporary fields (NotInClass option assigned).

21-18

Using a Derivation Rule Field Values in Rule Context

21.10 Field Values in Rule Context

Any computation involving field values that have different lengths or types changes the value of the target field in the rule context. For example, a derivation rule is used to move a value from one field to another field (value of fielda to fieldb):
FIELDA is moved to FIELDB.

If the length of the two fields are not the same, the value for the target field (fieldb) is implicitly changed in the rule context.

21.11 Target Specification via Derivation Rule Syntax

There are two ways to specify a target definition via the derivation rule syntax: staticallythe target composite/class name or number is explicitly listed in the rule dynamicallythe value for the target composite/class is specified by fields and resolved according to the field values during application processing.

Cross references between the target and the rule are only managed when the target is specified statically.

To specify a target via the rule syntax:

1 From the Logic tab on the Navigation pane of Development Workbench access the definition form for the rule. 2 Leave the target textbox blank. 3 Compose the derivation rule using the syntax listed below ("Derivation Rule Syntax with Target Specification" on page 21-22). 4 Specify the target in the rule syntax.

Field Specification
Fields can be explicitly specified and/or dynamically matched from the context according to the target definition. In order to use fields dynamically the rule must include the FIELDS ARE MATCHED clause. Explicit field specification overrides matched fields. Matched fields are applicable to path, key and derived fields.
21-19

21

Using a Derivation Rule Specifying an Operation as the Target for a Derivation Rule

Path and Key Fields

When matched fields are not used, the rule must explicitly specify all key and path fields. When matched fields are used, path and key fields are found from the class definition and their value is taken from the context. A partial list of key and path fields can be specified explicitly. In this case only the missing fields are matched. All path and Key fields must exist in the rule context.

Derive Fields
When matched fields are not used, fields that are to be derived must be explicitly specified. When matched fields are used, class data fields (i.e. fields that are neither key nor path fields) that are found in the context are used for the derivation. Class fields that are not in the context are ignored. Matched fields are always moved. If another action is needed the field must be explicitly specified.

Options
Options are listed in the {c-options} syntax. See Form Reference for an explanation of the options.

21.12 Specifying an Operation as the Target for a Derivation Rule

The following applies when specifying an operation as the target for a derivation rule: Operations invoked via derivation rules are queued in the queue used for delayed BLP commands and executed during commit processing. An error in executing the operation causes roll back. The runtime behavior of the derived operations is compatible with regular derivations. Issue rules are immediately executed at the start of a derived operation. Delayed derivations, created by the derived operation, are executed after all the derived operations in the queue.

21-20

Using a Derivation Rule Specifying an Operation as the Target for a Derivation Rule

Immediate derivations, created by the derived operation, are executed as part of the derived operation. The user can control wether derived operations are written or not written to the journal.

Target Specification
There are two ways to specify a target operation via the derivation rule syntax: staticallythe target operation name or number is explicitly listed in the rule dynamicallythe values for the target operation are specified by fields and resolved according to the field values during application processing.

Field Specification
The operation fields can be specified in any of the following ways:

By name of one or more fieldsIn this mode the fields must also be defined in the operation (with the identical name). Via a value (expression, constant or another field) and an operation field. The value is copied to the field. Via the FIELDS ARE MATCHED clauseIndicates that all the fields in the context that are also fields in the operation are to be used. In this implied mode the field role is according to the field definition in the operation.

Key fields are matched according to the definition of the operation target class. When a field is defined twice in an operation and is matched from the context, the first occurrence is used. The role for explicit fields (added, subtracted, etc.) is used as verification for selecting the field in the operation (using the field role in the operation definition). A rule field with a move role can verify fields defined in the operation with move, add or subtract roles. A verify role must be used only for a verify field in the operation.

Options
The NoJournal option means that the operation is not written to the journal (the default is to write to the journal).
21-21

21

Using a Derivation Rule Derivation Rule Syntax with Target Specification

21.13 Derivation Rule Syntax with Target Specification

21-22

Using a Derivation Rule Derivation Rule Syntax with Target Specification

The following is an example of a target specification in the derivation rule syntax: Example: A computation rule sets the value of the target composite and target class fields according to a condition (partial syntax shown). A derivation rule uses the calculated fields for setting the target composite and class and uses the FIELDS ARE MATCHED clause to implicitly select the fields from the context according to the class definition.

21-23

21

Using a Derivation Rule Invoking an Operation via a Derivation Rule

IF.... THEN dynamic-composite IS COMPUTESD AS.... dynamic-class IS COMPUTED AS... ELSE dynamic-composite IS COMPUTESD AS.... dynamic-class IS COMPUTED AS... DERIVE CLASS SPECIFIED BY dynamic-class OF COMPOSITE SPECIFIED BY dynamic-composite FIELDS ARE MATCHED.

21.14 Invoking an Operation via a Derivation Rule

An operation can be invoked via a derivation rule. The following applies: The operation action (create, modify, remove) must be specified. Operation fields can be specified explicitly (on a field by field basis) or implicitly matched from the context. A field action can be specified for each field. This is useful when a field appears more than once in an operation. The user can control wether derived operations are written or not written to the journal.

Target Specification
There are two ways to specify the target operation via the derivation rule syntax: staticallythe operation name or number is explicitly listed in the rule dynamicallythe value for the operation is specified by a field and resolved according to the field value during application processing.

To invoke an operation via a derivation rule:

1 From the Logic tab on the Navigation pane of Development Workbench access the definition form for the rule. 2 Leave the target textbox blank. 3 Compose the derivation rule using the syntax listed below ("Derivation Rule Syntax for Invoking an Operation" on page 21-26). 4 Specify the operation in the rule syntax.

21-24

Using a Derivation Rule Invoking an Operation via a Derivation Rule

Field Specification
The operation fields can be specified in any of the following ways:

By name of one or more fieldsIn this mode the fields must also be defined in the operation (with the identical name). For each field its operation checkset (action) can also be specified. Via a value (expression, constant or another field) and an operation field. The value is copied to the field. An operation checkset (action) can also be specified. Via the FIELDS ARE MATCHED clauseIndicates that all the fields in the context that are also fields in the operation are to be used. In this implied mode an operation checkset cannot be specified.

Fields that are explicitly specified override implicit specification. When a checkset is not specified, the first field in the operation with a matching number is used. When FIELDS ARE MATCHED is not used, the operation defaults are used for fields that are not explicitly specified.

Execution mode
The operation is activated (depending on the condition) even when no fields are specified. All operation rules are executed. Only one operation is invoked (no positive thinking). When the rule is triggered for change, the new values are used. Operations invoked via derivation rules are queued in the queue used for delayed BLP commands and executed during commit processing. An error executing the operation causes roll back.

Options
The NoJournal option means that the operation is not written to the journal (the default is to write to the journal).

21-25

21

Using a Derivation Rule Derivation Rule Syntax for Invoking an Operation

Operation Invoked On a Party

An operation can be invoked on a party. Operations invoked on a party are immediately written to the partys file. An operation written immediately cannot be aborted. When party is specified, options (e.g. NoJournal) cannot be specified.

In the current version, only a party with an active channel having File specified for its Message Format, is supported.

21.15 Derivation Rule Syntax for Invoking an Operation

Use the following syntax to invoke an operation via a derivation rule:

21-26

Using a Derivation Rule Derivation Rule Syntax for Invoking an Operation

21-27

21

Using a Derivation Rule Derivation Rule Syntax for Invoking an Operation

21-28

Chapter 22 Dynamic Rule Processing

Dynamic rule processing enables derivation and fetch rules to use dynamically calculated field and target values.

22.1 Dynamic Fields in Rules

Dynamic fields allow you to write rule statements that contain field objects that reference other fieldsthus allowing the field value used by the rule to be changed dynamically. By using a dynamic field in a rule statement you instruct the rule to use the value of the field that is pointed to by the field you specify in the dynamic field clause. You specify a dynamic field in a rule by preceding the field name and/or number with an at symbol (@).

This indicates to eMerge that the value of the field preceded by the ampersand is not a data value to be used when executing the rule but is the number of another eMerge field whose value you want to use when executing the rule. You can use other rules to dynamically change the value of the dynamic field (the one preceded by the ampersand) thereby giving the rule dynamic access to any eMerge field value. All fields referenced by a dynamic field must be in the rule context.

If you are uncertain if a field (e.g. Field3, #30000) that is referenced by a dynamic field is in the rule context, use a rule statement such as: Field3 must be eq to Field3., to put the field in the rule context.

Example: @Field1 is targetkey for Field2. The value of Field1 is 30000. The value of field #30000 is used when the rule is executed.

22-1

22

Dynamic Rule Processing Target Specification via Derivation Rule Syntax

22.2 Target Specification via Derivation Rule Syntax

A derivation rule is used to: update a target concept or composite/class The target to be updated can be specified via: rule definition form See "Using a Derivation Rule" on page 21-1 for details. rule syntax See "Derivation Rule Syntax with Target Specification" on page 22-5.

invoke an operation See "" on page 22-8.

Target Specification
There are two ways to specify a target definition via the derivation rule syntax: staticallythe target composite/class name or number is explicitly listed in the rule dynamicallythe value for the target composite/class is specified by fields and resolved according to the field values during application processing.

Cross references between the target and the rule are only managed when the target is specified statically.

To specify a target via the rule syntax:

1 From the Logic tab on the Navigation pane of Development Workbench access the definition form for the rule. 2 Leave the target textbox blank. 3 Compose the derivation rule using the syntax listed below ("Derivation Rule Syntax with Target Specification" on page 22-5). 4 Specify the target in the rule syntax.

Field Specification
Fields can be explicitly specified and/or dynamically matched from the context according to the target definition. In order to use fields dynamically the rule must include the FIELDS ARE MATCHED clause.

22-2

Dynamic Rule Processing Derive via Operations

Explicit field specification overrides matched fields. Matched fields are applicable to path, key and derived fields.

Path and Key Fields

When matched fields are not used, the rule must explicitly specify all key and path fields. When matched fields are used, path and key fields are found from the class definition and their value is taken from the context. A partial list of key and path fields can be specified explicitly. In this case only the missing fields are matched. All path and Key fields must exist in the rule context.

Derive Fields
When matched fields are not used, fields that are to be derived must be explicitly specified. When matched fields are used, class data fields (i.e. fields that are neither key nor path fields) that are found in the context are used for the derivation. Class fields that are not in the context are ignored. Matched fields are always moved. If another action is needed the field must be explicitly specified.

Options
Options are listed in the {c-options} syntax. See General Reference for an explanation of the options.

22.3 Derive via Operations

The following applies when specifying an operation as the target for a derivation rule: Operations invoked via derivation rules are queued in the queue used for delayed BLP commands and executed during commit processing. An error in executing the operation causes roll back. The runtime behavior of the derived operations is compatible with regular derivations. Issue rules are immediately executed at the start of a derived operation.
22-3

22

Dynamic Rule Processing Derive via Operations

Delayed derivations, created by the derived operation, are executed after all the derived operations in the queue. Immediate derivations, created by the derived operation, are executed as part of the derived operation. The user can control wether derived operations are written or not written to the journal.

Target Specification
There are two ways to specify a target operation via the derivation rule syntax: staticallythe target operation name or number is explicitly listed in the rule dynamicallythe values for the target operation are specified by fields and resolved according to the field values during application processing.

Field Specification
The operation fields can be specified in any of the following ways:

By name of one or more fieldsIn this mode the fields must also be defined in the operation (with the identical name). Via a value (expression, constant or another field) and an operation field. The value is copied to the field. Via the FIELDS ARE MATCHED clauseIndicates that all the fields in the context that are also fields in the operation are to be used. In this implied mode the field role is according to the field definition in the operation.

Key fields are matched according to the definition of the operation target class. When a field is defined twice in an operation and is matched from the context, the first occurrence is used. The role for explicit fields (added, subtracted, etc.) is used as verification for selecting the field in the operation (using the field role in the operation definition). A rule field with a move role can verify fields defined in the operation with move, add or subtract roles. A verify role must be used only for a verify field in the operation.

22-4

Dynamic Rule Processing Derivation Rule Syntax with Target Specification

Options
The NoJournal option means that the operation is not written to the journal (the default is to write to the journal).

22.4 Derivation Rule Syntax with Target Specification

22-5

22

Dynamic Rule Processing Derivation Rule Syntax with Target Specification

22-6

Dynamic Rule Processing Derivation Rule Syntax with Target Specification

The following is an example of a target specification in the derivation rule syntax: Example: A computation rule sets the value of the target composite and target class fields according to a condition (partial syntax shown). A derivation rule uses the calculated fields for setting the target composite and class and uses the FIELDS ARE MATCHED clause to implicitly select the fields from the context according to the class definition.

22-7

22

Dynamic Rule Processing Invoking an Operation via a Derivation Rule

IF.... THEN dynamic-composite IS COMPUTESD AS.... dynamic-class IS COMPUTED AS... ELSE dynamic-composite IS COMPUTESD AS.... dynamic-class IS COMPUTED AS... DERIVE CLASS SPECIFIED BY dynamic-class OF COMPOSITE SPECIFIED BY dynamic-composite FIELDS ARE MATCHED.

22.5 Invoking an Operation via a Derivation Rule

An operation can be invoked via a derivation rule. The following applies: The operation action (create, modify, remove) must be specified. Operation fields can be specified explicitly (on a field by field basis) or implicitly matched from the context. A field action can be specified for each field. This is useful when a field appears more than once in an operation. The user can control wether derived operations are written or not written to the journal.

Target Specification
There are two ways to specify the target operation via the derivation rule syntax: staticallythe operation name or number is explicitly listed in the rule dynamicallythe value for the operation is specified by a field and resolved according to the field value during application processing.

To invoke an operation via a derivation rule:

1 From the Logic tab on the Navigation pane of Development Workbench access the definition form for the rule. 2 Leave the target textbox blank. 3 Compose the derivation rule using the syntax listed below ("Derivation Rule Syntax for Invoking an Operation" on page 22-9).

4 Specify the operation in the rule syntax.

22-8

Dynamic Rule Processing Derivation Rule Syntax for Invoking an Operation

Field Specification
The operation fields can be specified in any of the following ways:

By name of one or more fieldsIn this mode the fields must also be defined in the operation (with the identical name). For each field its operation checkset (action) can also be specified. Via a value (expression, constant or another field) and an operation field. The value is copied to the field. An operation checkset (action) can also be specified. Via the FIELDS ARE MATCHED clauseIndicates that all the fields in the context that are also fields in the operation are to be used. In this implied mode an operation checkset cannot be specified.

Fields that are explicitly specified override implicit specification. When a checkset is not specified, the first field in the operation with a matching number is used. When FIELDS ARE MATCHED is not used, the operation defaults are used for fields that are not explicitly specified.

Execution mode
The operation is activated (depending on the condition) even when no fields are specified. All operation rules are executed. Only one operation is invoked (no positive thinking). When the rule is triggered for change, the new values are used. Operations invoked via derivation rules are queued in the queue used for delayed BLP commands and executed during commit processing. An error executing the operation causes roll back.

Options
The NoJournal option means that the operation is not written to the journal (the default is to write to the journal).

22.6 Derivation Rule Syntax for Invoking an Operation

Use the following syntax to invoke an operation via a derivation rule:

22-9

22

Dynamic Rule Processing Derivation Rule Syntax for Invoking an Operation

22-10

Dynamic Rule Processing Derivation Rule Syntax for Invoking an Operation

22-11

22

Dynamic Rule Processing Target Specification via Fetch Rule Syntax

22.7 Target Specification via Fetch Rule Syntax

A fetch rule is used to retrieve data from a target concept or composite/class.

Target Specification
The target for the rule can be specified via: rule definition form See "Using a Fetch Rule" on page 18-1 for details. rule syntax See "Fetch Rule Syntax with Target Specification" on page 22-13. There are two ways to specify a target definition via the fetch rule syntax: staticallythe name or number of the composite/class is explicitly listed in the rule dynamicallythe value for the composite/class is calculated dynamically during application processing

To specify a target via the rule syntax:

1 From the Logic tab on the Navigation pane of Development Workbench access the definition form for the rule. 2 Leave the target textbox blank. 3 Compose the fetch rule using the syntax listed below ("Fetch Rule Syntax with Target Specification" on page 22-13). 4 Specify the target in the rule syntax.

Options
Options are listed in the {f-options} syntax. See General Reference for an explanation of the options.

22-12

Dynamic Rule Processing Fetch Rule Syntax with Target Specification

22.8 Fetch Rule Syntax with Target Specification

22-13

22

Dynamic Rule Processing Fetch Rule Syntax with Target Specification

22-14

Chapter 23 Temporary Composites

The data for the composite of an implemented concept is, by default, stored in a physical database. However, sometimes it is advantageous for an application to have the data for the composite temporarily available in task memory, and not stored in the database. Such a composite, whose data only exists temporarily in task memory, is referred to as a temporary composite. A temporary composite is an eMerge composite hierarchy that includes class and field objects. The temporary composite is mapped into task memory and does not exist in permanent storage. It behaves like a hierarchal context in task memory. A temporary composite has the following features:

No I/O is performed when writing and reading to/from a temporary composite. A temporary composite hierarchy remains in task memory so that it is available to all operations in a group of operations being processed in group mode (it is not deleted after an operation in a group is implementedonly after a commit is performed). Rules can update data in a temporary composites. A temporary composite in task memory behaves vis-a-vis rules the same as a composite stored on a physical database. Rules can fetch and derive from/to the temporary composite, update, and delete data in the temporary composite. For example, a derivation rule can derive directly to a temporary composite hierarchy (by assigning to the derivation the ImmediateExecution option), thus avoiding the queue used for derivations. See "Using Temporary Composites with Derivation Rules" on page 23-5. Since a temporary composite behaves as a hierarchical context in task memory, complex information can be passed between operations, derivations, queries and a temporary composite, without the need to write a program or to manage a database composite.

23-1

23

Temporary Composites Options Supported

Data manipulations, that can be performed on any composite stored in a physical database, can also be performed on a temporary composite stored in task memory, for example: data can be entered into the temporary composite via rules data can be passed via rules to programs queries can be run on the temporary composite data A temporary composite is normally deleted from task memory after commit. However, if commands are issued via the BlpCmdDelay function (see "Using Built-In Functions in Rules" on page 24-1), a temporary composite is deleted after the commands are executed. Example: If a set of operations are being performed in group mode (GROUP ON in effect), the temporary composite is deleted after GROUP OFF is issuedif no commands have been issued via the BlpCmdDelay function.

23.1 Options Supported

When working with temporary composites, the following options are supported: For the composite:

OneToOne Auto InsertFifo

For the class:

For the derivation rule: See "Using Temporary Composites with Derivation Rules" on page 23-5.

23.2 Enabling Temporary Composites

To work with temporary composites, task memory must be increased according to the amount of data that is stored into the application. The task memory key must be equal to largest temporary composite key defined in the database. The value in the Initial Length field in the Composite Definition form is taken into account when calculating memory usage. If no value is listed on the form for the field, 1024 bytes are allocated.

23-2

Temporary Composites Defining a Temporary Composite

23.3 Defining a Temporary Composite

1 Via Modeler, right-click the concept. From the pop-up menu displayed, choose Object > Concept Design. The Concept Design (2013) form is displayed:

2 Right-click in the Design textbox. Select Design Objects from the pop-up menu that is displayed. Select Composite:

23-3

23

Temporary Composites Defining a Temporary Composite

The Composite Definition (100301) form is displayed:

3 From the Memory Usage category assign the TemporaryComposite property to the composite. 4 Depending on the number of fields in the composite, increase the value for the temporary composite Initial Length (if needed).

Each variable field in the temporary composite is allocated 80 bytes. The temporary composite itself is initially allocated a length of 1024 bytes (when the Initial Length field value is left empty).

5 Click OK.

23-4

Temporary Composites Using Temporary Composites with Derivation Rules

23.4 Using Temporary Composites with Derivation Rules

Normally, derivations that are waiting for execution are added to a queue where they await implementation. When deriving to a temporary composite, the queue can be avoided by assigning the ImmediateExecution to a derivation rule. The derivation rule assigned ImmediateExecution derives directly to a temporary composite hierarchy. A derivation assigned ImmediateExecution cannot derive between fields of different lengths or types, nor can it add, subtract or verify fields. When working with temporary composites and invoking a derivation with Immediate Execution, the following options are supported for the target:

Secondary InsertEqualChange ActualValue MayChangeNothing IgnoreMissingTarget IgnoreMissingPath

The following target options are not supported for a derivation rule assigned ImmediateExecution: MayChangeNothing SecondaryMeaning NoOperationOnBlank RetroactiveInsert MainTarget MultiOccurrence MultiPath The following class options are not supported for a derivation rule assigned ImmediateExecution: NoAutoDelete MayReplaceKey Recursive DeleteSonsOnDerive NoDeleteParent MayDelteSonsOnDerive

23-5

23

Temporary Composites Using Temporary Composites with Derivation Rules

To assign the ImmediateExecution to a derivation:

1 From the Derivation Rule (200007) form, click in the Ruleset textbox and assign ImmediateExecution from the Derivation category.

2 Click OK.

23-6

Chapter 24 Using Built-In Functions in Rules

eMerge rules provide for the use of functions within rules. Functions are easily implemented into the rule statement text providing an increased rule calculation capability. For example, the following Validation rule uses a function:
if OVERTIME-DAY eg WeekDayOfDate(date) then PREMIUM must be 100.

24.1 What are Functions?

Functions perform calculations or data manipulation. A function is used directly in the rule text statement when composing a rule. A function can be used in the following:

IF, WHERE,

and WHILE rule statement clauses.

Computation and fetch rules as part of an arithmetic statement. A validation rule (on the right-hand-side of the validation rule statement). Computation and derivation rules as an assigned expression (on the right-hand-side of the rule statement). As a value for path or a target field in a fetch or derivation rule.

Each function has the following: Function Name The function name identifies the function.

Function Parameters The function parameters (arguments) specify the input parameters required by the function. Returned Value The result of the function calculation is a single valuethe returned value of the function.

24-1

24

Using Built-In Functions in Rules Built-In Functions

There are two types of functions used in rules. Both types of functions are grouped into function categories, for display in the navigation pane, according to their functionality.

Built-in functionseMerge supplied functions that perform date, time, system, string and arithmetic manipulations. Built-in functions are described in this chapter. User-defined functionsFunctions defined by the user that call a user function written in C when working in i5/OS, HP-UX, or Linux. For more on user-defined functions, see Chapter 25, Using User-Defined Functions in Rules (i5/OS, HP-UX, and Linux).

24.2 Built-In Functions

The names of eMerge built-in functions are listed below. For a detailed description of each of the functions refer to the Built-In Function chapter in General Reference. Function Category Date Manipulation Age DayOfDate IsLeapYear LastDay ThaiIsLeapYear ThaiLastDay Calculates age in years for a given birth date and current date. Retrieves the day from a date. Indicates if a given date is a leap year. Obtains the last day of the month for a given date. Indicates if a given Thai date is in a leap year. Obtains the last day of the month for a given Thai date. Function Name Description

ThaiWeekDayOfDate Calculates the number of the day in the week for a given Thai date (e.g. 1, 2, ...7, where 1 is Sunday, 2 is Monday,...). ThaiWeekInYear MonthOfDate WeekDayOfDate Obtains the number of the week in the year for a given Thai date (i.e. 1-52). Retrieves the month from a date. Calculates the number of the day in the week.

24-2

Using Built-In Functions in Rules Built-In Functions

Function Category

Function Name WeekInYear YearOfDate

Description Obtains the number of the week in the year for a given date. Retrieves the year from a date. Indicates if a field is in the rule context. Returns a two character string based on a calculation performed on a nine digit number. Converts a given date and time to XML or DB2 formats. Obtains the modulus (remainder) when dividing a given number by a given divisor. Raises an integer to an integer power. Rounds a numeric string representation of a number to a given decimal position. Indicates if a given numeric string representation of a number is greater than zero, equal to zero, or less than zero. Truncates a numeric string representation of a number to a given decimal position. Joins two strings, each padded by a specified character to a specified length. Joins two strings (with a character in between them). Returns the numeric characters of a string, concatenated. The non-numeric characters of the string are discarded. Indicates if a given string contains only digits. Removes leading and trailing blanks from a string. Compares the length of two strings.
24-3

General IsFieldInContext SSNCheckDigit

TimeStampConvert Mathematical Modulus Power Round Sign

TruncateNumber String Manipulation ConcatByLength Concatenate GetDigits

IsNumeric RemovePaddings StringCompare

24

Using Built-In Functions in Rules Built-In Functions

Function Category

Function Name StringLength StringPosition Substring SubstringByWord SubstringLast SubstringReplace ValidName WordCount

Description Finds the length of a string. Locates the position of a substring in a target string. Extracts a substring of characters from a target string. Extracts a substring of words from a target string. Obtains the last n characters from a string. Replaces every occurrence of substring1 in a given string with substring2. Replaces word deliminators in a string with a single word deliminator type. Calculates the number of words in a string. Issues a BLP command. The command is performed after the operation has completed but before COMMIT has been performed. Issues one of these trace commands:

System Manipulation BLPCmdDelay

BLPCmdImmed

TRACE SNAP TRACE DBMS ON / OFF SNAP TRACE SQL ON / OFF

The command is performed immediately CreateID Returns a unique string that consists of a timestamp concatenated with a user defined string. Calculates the sum of the values of two time formatted field values. A time formatted field value has the following representation: HHHHHMMSS.XXXXXX. Creates a time formatted field value from hours, minutes, seconds, and parts of a second information. Gets the fraction of a second part for a time formatted field (i.e. XXXXXX).

Time Manipulation TimeAdd

TimeCreate

TimeFraction

24-4

Using Built-In Functions in Rules Function Syntax

Function Category

Function Name TimeHours TimeMinutes TimeOperation

Description Gets the hour part for a time formatted field (i.e. HHHHH). Gets the minute part for a time formatted field. Retrieves the value of the global field Current Time as recorded in the journal for the operation. Gets the seconds part for a time formatted field. Calculates the difference between two time formatted field values (i.e. the elapsed time). Obtains a decimal format representation for a time formatted field value. Converts a time formatted field value into a string.

TimeSeconds TimeSubtract TimeToDecimal TimeToString

Example: A date field defined in the knowledgebase is used in a rule. In order to perform a day-of-the-week dependent premium calculation, it is required to know what is the number of the day in the week for the particular date specified (e.g. is it day 1, day 2,... or day 7?). A built-In function (WeekDayOfDate) is provided by eMerge to calculate the number of the day in the week for any valid date value. In this example, WeekDayOfDate is the function name, a valid eMerge date value (e.g. 21 Jun 2001) is the input parameter and the number of the day in the week (for the input date value supplied) is the returned value. In particular, for the input date 21 Jun 2001, the returned value is 5 (Thursday).

24.3 Function Syntax

{funcexp} represents the function expression containing the syntax for a function.

24-5

24

Using Built-In Functions in Rules Function Categories

The left parenthesis is the beginning of the function parameter list. The right parenthesis is the end of the function parameter list. A parameter can be empty, an expression or a function. A comma (,) separates the parameters of a function. An empty parameter is represented by two successive commas. {funcexp} is used in rule text as part of other rule statement expressions. {funcexp} can be used directly in the following expressions: {arithexp}, {stringexp}, {list}, and {condexp}. {funcexp} can be incorporated into the following expressions: {value}, {validation}, {assignment}, {basicassign}, the right side of {validation}, {calcval}, {updatedef} and part of {targetdef}. {funcexp} is incorporated into these expressions by using {funcexp} in {arithexp} and in {stringexp} and then using {arithexp} and {stringexp} in these expressions. For syntax details on how to use {funcexp} directly in expressions see General Reference.

24.4 Function Categories

Functions are classified according to their function category. The following are the names of the eMerge built-In function categories:

Mathematical String (only supported for single-byte character sets) Date Conversion System General

24.5 Accessing a Function Category

Via Development Workbench you access the function categories.

24-6

Using Built-In Functions in Rules Accessing a Function Definition

To access a function category:

1 From the Logic tab of the Navigation Pane of Development Workbench, expand Integration > Functions. The function categories are displayed:

2 Expand a category to access the functions in the category.

24.6 Accessing a Function Definition

To access the definition of a function, first access the function category and then display the Function Definition form for the particular function in the category.

To access a Function Definition form:

1 Expand a particular function category (e.g. String) or right-click the category name and choose Open Category. A list of functions in the category is displayed:

24-7

24

Using Built-In Functions in Rules Implementing Functions in a Rule

2 Double-click a function from the list of functions (e.g. StringLength). The Function Definition (20460) form is displayed:

Right-click the function name and choose Open Function.

24.7 Implementing Functions in a Rule

A function is used in a rule statement by specifying the name of the function and its parameters.

To use a function in a rule:

1 Using Modeler, access the rule definition form for the particular rule. 2 Enter rule statement text in the Rule Text textbox and include any functions required directly in the rule statement. The location in a rule statement expression where {funcexp} can appear (i.e. in {arithexp}, {stringexp}, {condexp}, {list}) is listed in General Reference. If Rule Editor is enabled (RULEEDITOR ON command entered into the Execute Command box of Development Workbench) you can obtain a prompt that indicates where a function can be used in the rule text and that assists in selecting functions and entering their parameters.

24-8

Using Built-In Functions in Rules Examples of Functions in Rules

3 Compile the rule.

Function Names
Use the eMerge built-in function name listed in "Built-In Functions" on page 24-2.

Function Parameters
Parameters used in a function must be defined in the knowledgebase. A function can have several input parameters. The output of the function is its returned value. Parameters are separated from each other by a comma. The parameter data type should match that required by the function definition (refer to the chapter in General Reference for built-in function definitions and parameter requirements). If parameters are passed to a function that have a type different from the defined parameter type, eMerge attempts to perform data conversion on the parameter data type to comply with the required parameter type. If data conversion fails an error is generated.

24.8 Examples of Functions in Rules

Following are examples of rules using functions:

Computation Rule
Example: A character field Employee-Name-FL has for its value the name of an employee, John Doe. This field value has the first-name followed by the last-name. It is required to list the employee names, last-name first, first-name last. The following computation rule reverses the words of the value of field Employee-Name-FL, and stores the answer, Doe John, in character field Employee-Name-LF. The computation rule uses the SubstringByWord and Concatenate built-In functions:
EMPLOYEE-NAME-LF is stored as Concatenate(SubstringByWord(EMPLOYEE-NAME-FL,2,1), SubstringByWord(EMPLOYEE-NAME-FL,1,1), " ").

24-9

24

Using Built-In Functions in Rules Examples of Functions in Rules

The function SubstringByWord extracts the second word (Doe) and the first word (John) from the string Employee-Name-FL (John Doe). The function Concatenate appends the first word (John) to the second word (Doe) with a blank character in between, forming the new string Employee-Name-LF (Doe John).

The characters blank, minus, or asterisk, when used as the concatenation character in the function Concatenate, must be enclosed within double and single quotation marks.

24-10

Chapter 25 Using User-Defined Functions in Rules (i5/OS, HP-UX, and Linux)

eMerge rules provide for the use of functions within rules. Functions can be inserted into the rule text to provide increased calculation capability. User-defined functions allow you to customize your rules by calling your functionswritten in C code. For example, the following validation rule uses a function:
if OVERTIME-DAY eg WeekDayOfDate(date) then PREMIUM must be 100.

25.1 What are Functions?

Functions perform calculations or data manipulation. A function is used directly in the rule text statement when composing a rule. A function can be used in the following:

IF, WHERE,

and WHILE rule statement clauses.

Computation and fetch rules as part of an arithmetic statement. A validation rule (on the right-hand-side of the validation rule statement). Computation and derivation rules as an assigned expression (on the right-hand-side of the rule statement). As a value for path or a target field in a fetch or derivation rule.

Each function has the following: Function Name The function name identifies the function.

Function Parameters The function parameters (arguments) specify the input parameters required by the function. Returned Value The result of the function calculation is a single valuethe returned value of the function.
25-1

25

Using User-Defined Functions in Rules (i5/OS, HP-UX, and Linux) Function Syntax

There are two types of functions used in rules. Both types of functions are grouped into function categories, for display in the navigation pane, according to their functionality.

Built-in functionseMerge supplied functions that perform date, time, system, string and arithmetic manipulations. For more on eMerge built-in functions, see Chapter 24, Using Built-In Functions in Rules. User-defined functionsFunctions defined by the user that call a user function written in C. User-defined functions are described in this chapter.

25.2 Function Syntax

{funcexp} represents the function expression containing the syntax for a function.

The left parenthesis is the beginning of the parameter list. The right parenthesis is the end of the parameter list. A parameter can be empty, an expression or a function. A comma (,) separates the parameters of a function. An empty parameter is represented by two successive commas. {funcexp} is used in rule text as part of other rule statement expressions. For syntax details on how to use {funcexp} in rule statement expressions (e.g. {arithexp}, {stringexp}, {condexp}, {list}) see General Reference.

25.3 Function Categories

Functions are classified, for display on the navigation pane of Development Workbench, according to category. Via Development Workbench you can define a new function category and delete an existing user-defined category. You can place user-defined functions into user defined categories or into one of the following eMerge built-in function categories:

Mathematical String

25-2

Using User-Defined Functions in Rules (i5/OS, HP-UX, and Linux) Function Definitions

Date Conversion System General Time

Defining a New Function Category

You can specify your own function categories. 1 Right-click Functions on the Logic tab and choose New Category to display the Function Category (20468) form:

2 Enter a name for the function category, in the Category Name textbox. 3 Enter the name of the icon you want to display alongside the function category name. 4 Click OK.

Deleting a User-defined Function Category

Right-click the category name and choose Delete Category.

25.4 Function Definitions

From within a function category you can do the following:

define a new user-defined function

25-3

25

Using User-Defined Functions in Rules (i5/OS, HP-UX, and Linux) Function Definitions

access an existing function definition (built-in or user-defined) delete an exiting user-defined function

A runtime module must be specified for a user-defined function. The module can contain one or more user-defined functions. For example, a specific module can contain user-defined functions belonging to a similar category or user-defined functions that perform similar tasks (e.g. the Premium module may contain many user-defined functions that are used to calculate insurance premiums). The module is generated, compiled and linked by an eMerge utility DBCMODL (see "Module Generation and Compilation" on page 25-8). The module is invoked, at runtime, when a user-defined function in the module is referenced in a business rule.

Defining a New Function

A user-defined function must be defined in the eMerge knowledgebase. Information provided in the function definition is used at module generation time, to generate the module invoked at run time. Once defined, user-defined functions are used directly in rule text just as eMerge built-in functions are used. 1 Using Modeler, click the Logic tab on the Navigation Pane. Expand Integration > Functions. Right-click a category in which you want to place

25-4

Using User-Defined Functions in Rules (i5/OS, HP-UX, and Linux) Function Definitions

the new function. Choose New Function from the pop-up menu to display the Function Definition (20460) form:

2 Enter a name for the function in the Function textbox. 3 Enter a name for the runtime module called by the function in the Module textbox. The module interfaces between the function definition in the knowledgebase and the requirements of the user-defined function. 4 Indicate the language in which the user-defined function is written, by choosing a language in the Language field: Cobol, PL/1, or C.

25-5

25

Using User-Defined Functions in Rules (i5/OS, HP-UX, and Linux) Function Definitions

5 Specify the input and output parameters required by the function, in the Parameters groupbox:

In the Field textboxes, enter the eMerge field number and name, as defined in the knowledgebase, that contains the function parameter. In the Name in Function textbox, specify the name by which the parameter is called in the function. Assign Input or Return to the parameter to define the parameter as an input or output parameter.

Accessing an Existing Function Definition

To access the definition for a function, you first access the category and than display the Function Definition form for a function in the category.

Accessing an Existing Function Category

1 From the Logic tab of the navigation pane of Development Workbench, expand Integration > Functions. The function categories are displayed:

25-6

Using User-Defined Functions in Rules (i5/OS, HP-UX, and Linux) Function Definitions

2 Expand a particular category (e.g. String). A list of functions in the category is displayed:

3 Double-click a function from the list of functions (e.g. stringGetLength). The Function Definition (20460) form is displayed:

25-7

25

Using User-Defined Functions in Rules (i5/OS, HP-UX, and Linux) Module Generation and Compilation

Deleting a User-Defined Function

To delete a user-defined function, right-click the function name and choose Delete Function.

25.5 Module Generation and Compilation

The Create eMerge User Function utility (see Business Integrity Server Utility Reference) must be run to create a runtime module. The module is based on the function definition in the knowledgebase and on the supplied user function code.
knowledgebase definitions for user-defined functions

Create eMerge User Function Utility

Interface user-defined function names with eMerge: Abs, StrLen
Generate Code

Interface user-defined function parameter definitions with eMerge: MyNum, Str, Bin Insert user-defined function code

Compile module Link

runtime

user function source code

Insert Code

StrLen Abs

specify path via library list option

25.6 Specifying the User-defined Function

The user-defined function can be specified in either of these ways:

by referencing the location for user the functionlisting the path to the user function in the Library list option by inserting the user function source code directly in the generated code fragmentvia the Insert user function code option.

25-8

Using User-Defined Functions in Rules (i5/OS, HP-UX, and Linux) Implementing Functions in a Business Rule

Example: The user has defined two functions for the module: Abs and StrLen. Function Abs has parameters MyNum and Bin. Function StrLen has parameters Str and Bin. For each user-defined function, the user inserts the function source code (at the locations indicated in the code fragment). The names of the parameters in the user functions are automatically modified by the system to always have their first character upper case (this avoids conflicts with reserved system names or reserved C language names):
*** Top of File *** #define USERFUNC_C #include "SAPFUNCH.H" void Abs(uChar MYNUM, short *Bin) { /* Insert User function Code Here!! */ } void Strlen(char *Str, short *Bin) { /* Insert User function Code Here!! */ } *** End of File ***

25.7 Implementing Functions in a Business Rule

A function is used in a business rule statement by specifying the name of the function and its parameters. 1 Using Modeler, access the rule definition form for the particular rule. 2 Enter rule statement text in the Rule Text textbox and include any functions required directly in the rule statement. The location in a rule statement expression where a function, {funcexp}, can appear (e.g. in {arithexp}, {stringexp}, {condexp}, {list}) is listed in the General Reference. If Rule Editor is enabled (RULEEDITOR ON command entered into the Execute Command box of Development Workbench) you can obtain a prompt that indicates where a function can be used in the rule text and that assists you in selecting functions and entering their parameters. 3 Compile the rule.

25-9

25

Using User-Defined Functions in Rules (i5/OS, HP-UX, and Linux) Example of Functions in a Computation Rule

Function Names
Use the user-defined function name as specified by the user (via the Function Definition (20460) form).

Function Parameters
Parameters used in a function must be defined in the knowledgebase. A function can have several input parameters. The output of the function is its returned value. Parameters are separated from each other by a comma. The parameter data type should match that required by the function definition. If parameters are passed to a function that have a type different from the defined parameter type, eMerge attempts to perform data conversion on the parameter data type to comply with the required parameter type. If data conversion fails, an error is generated.

25.8 Example of Functions in a Computation Rule

A character field Employee-Name-FL has for its value the name of an employee, John Doe. This field value has the first-name followed by the last-name. It is required to list the employee names, last-name first, first-name last. The following computation rule reverses the words of the value of field Employee-Name-FL, and stores the answer, Doe John, in character field Employee-Name-LF. The computation rule uses the stringGetWordSubstring and stringConcatenate built-in functions.
EMPLOYEE-NAME-LF is stored as Concatenate(SubstringByWord(EMPLOYEE-NAME-FL,2,1), SubstringByWord(EMPLOYEE-NAME-FL,1,1), " ").

The function stringGetWordSubstring extracts the second word (Doe) and the first word (John) from the string Employee-Name-FL (John Doe). The function stringConcatenate appends the first word (John) to the second word (Doe) with a blank character in between, forming the new string Employee-Name-LF (Doe John).

25-10

Chapter 26 Improving Rule Performance

eMerge automatically optimizes the performance of the rules in an application. For example, only rules that include fields that have been changed are executed. Additional optimization can be done dependent on the specific application.

26.1 Accessing a Target Object in Memory

The target object can be either in the same branch or a different branch of the same object hierarchy occurrence.

Accessing an Object Hierarchy that Includes the Triggering Object

If the target occurrence is an occurrence in the same object hierarchy as the triggering object occurrence, include this information as part of the rule definition. Once this information is included as part of the rule definition, a new access to disk is not necessary, since eMerge recognizes that the relevant object hierarchy already exists in memory. To specify that the target is in the same branch in the same object hierarchy, assign the SameBranch option to the fetch rule or to the derivation rule. To specify that the target is in different branch in the same object hierarchy, assign the SameComposite option.

You can assign the SameComposite option instead of the SameBranch option without receiving an error. However, this is less efficient.

For further details refer to "Retrieving an Occurrence from the Same Object Hierarchy" on page 18-13 or "Writing to an Existing Target Occurrence" on page 21-14. If you do not know whether the target occurrence for a fetch rule is in the same target hierarchy occurrence as the triggering object occurrence, assign the MaySameComposite option for the target of the fetch rule.

26-1

26

Improving Rule Performance Changing the Execution Order for Target Objects

Accessing a Target Object Repeatedly

If a target object occurrence is repeatedly accessed by different fetch rules, assign the FetchInMemory option (Memory categroy)to the target of the fetch rule. In addition, assign the FetchInMemory option or the FetchInMemoryRoot option to the composite definition underlying the object hierarchy (in the Composite Definition (100301) form). The target object occurrence is accessed once and then kept in memory.

26.2 Changing the Execution Order for Target Objects

When a derivation rule is executed, an operation, called a derived operation, is created to update the target object. The update of the target triggers any rulesets which are attached to the target. Derivation rules in these rulesets are then triggered creating additional derived operations. The chain of these additional derived operations enter into one of two queues for implementation:

An internal queue for updates to the same object hierarchy (i.e. for the same occurrence). An external queue for updates to the another object hierarchy (either another occurrence in the same type of object hierarchy (e.g. to another occurrence of Employee) or a different type of object hierarchy (e.g. Accounts).

The classification of the derived operations into internal and external queues improves execution behavior and efficiency. Each time an object hierarchy is accessed by a derived operation and it is not already in memory, the following database operations are required:

One database read One database write One Log write

If the object hierarchy is already in memory, these operations are saved for each additional derived update to an object in the hierarchy. By grouping input operations and derivations into queues you can control whether additional database operations are required. The derived operations in the internal and external queues are executed after the original update to the triggering object has completed, including the execution of all of its rulesets. The derived operations in the internal queue are executed first, followed by the derived operations in the external queue. By default, the derived
26-2

Improving Rule Performance Changing the Execution Order for Target Objects

operations are executed according to the order in which they were created (during the execution of the originating derivation rules). That is, for each derivation queue the execution order is FIFO (First In First Out). When, because of an update to the target object by a derived operation, a new derivation rule is triggered and executed, the resulting new derived operation is added to the end of the appropriate queue.

Grouping Input Operations Using the Group Command

The execution order can be altered by grouping operations together, so that they are all accepted or all rejected as a group. Group operations together by issuing the Group command. The command works both in an online session or a batch run. When the Group command has been issued, grouping is in effect until the Group Off command is issued. (Online, every entry of a number of operations of the same type, is a group; in batch, all operations between a Group On command and a Group Off command are a group.) The command has two parameters that affect the execution order of derived operations:
ON Derived operations to the same object hierarchy occurrence are executed if, and when, there is an input operation in the group that targets a different object hierarchy occurrence, or if the target object is in a different branch in the target object hierarchy occurrence.

Derived operations to other object hierarchy occurrences are added to the external queue. They are executed after the execution of the group of input operations.

Assigning the Group option in a form definition (via the Form Definition (100675) form) localizes the effects of the feature to updates initiated from the specific data entry form.
IMMEDIATE

All derived operations from the input operation are executed immediately after the direct processing of the input operation has completed. That is, the derived operations are not processed after processing has completed for the group of input operations. This is equivalent to not issuing the Group command for the derived operations. If an operation in the group is rejected all of the derived updates have to be rolled back as the whole group of operations is no longer accepted. Only use this option when a derived update must complete before a subsequent input operation is processed, and you still want the input operations together in one batch.

26-3

26

Improving Rule Performance Changing the Execution Order for Target Objects

Assigning both the Group and the ImmediateDerivation options in a form definition (via the Form Definition (100675) form) localizes the effects of the feature to updates initiated from the specific data entry form.

Grouping Derivation Rules Physically

Derived operations to an object occurrence which is not part of the triggering object hierarchy occurrence are executed according to the order in which they are entered to the external derivation queue. This can result in unnecessary database read and write operations if the same object hierarchy is read from disk or written to a number of separate times.

Derived operations to an object in the same object hierarchy occurrence as the triggering object enter the internal derivation queue and are executed while the triggering object occurrence is still in memory.

Example: A derived operation is to object hierarchy X followed by a derived operation to object hierarchy Y. Neither hierarchy X, nor hierarchy Y are in the same object hierarchy as the triggering object. A third derived operation to the first object hierarchy (X) requires another read and write operation. If possible, change the order of the rules in the ruleset so that all derivations to one object hierarchy are executed one after the other. For details of how to change the order see "Ruleset Triggering Order Within a Model" on page 11-3. Example: The following two sets of rules show a derivation rule execution order which is inefficient and an order which is more efficient: Original order for the rules: Derivation rule 10 hierarchy X (read 1) Derivation rule 20 hierarchy Y (read 2) Derivation rule 30 hierarchy X (read 3) More efficient order for the rules: Derivation rule 10 hierarchy X (read 1, rule 10 above) Derivation rule 15 hierarchy X (rule 30 above) Derivation rule 20 hierarchy Y (read 2, rule 20 above)

26-4

Improving Rule Performance Changing the Execution Order for Target Objects

Grouping Derivation Rules LogicallyQueues

If you cannot change the order in which derivation rules are executed, you can group them logically into queues. The normal execution order for derived operations is FIFO. You can change this order, by grouping derivation rules that access the same object hierarchy occurrence together, into a queue. Assigning queues Assigning a queue to a derivation rule creates a subqueue, within the external queue. When a derived operation is inserted into a queue, it is added to the end of the subqueue instead of to the end of the entire queue. The execution order for the derived operations in the subqueue is FIFO. The subqueues are invoked according to the value of the queue specified for each subqueue in ascending order. That is, derived operations that are assigned a queue of 20 are executed before derived operations that are assigned a queue of 30. Any derived operations that are not assigned a queue are automatically assigned a queue of zero.
A negative queue can be defined. Define a rule with a negative queue if you want the derived operation executed before the derived operation created for a previous rule that you do not want to assign a queue (and which is, therefore, assigned the default queue of zero).

In the above example, assigning the same queue to derivation rule 10 and derivation rule 30 (the two rules that derive to hierarchy X), resolves the problem of the two database accesses. Within the internal and external queues there is an additional classification (New or Old) according to the operation (e.g. Input, Change, Delete) being performed. The New queue contains the derived operations that perform Input or Change operations, whereas the Old queue contains the derived operations that perform Change or Delete operations. When assigning a queue to a derivation rule you assign the queue number to the New or Old queues as per the operation performed (Insert/Change or Change/Delete).

To assign a queue:

1 Access the Derivation Rule (200007) form and display the relevant derivation. 2 Assign a queue (i.e. a queue number) to one of the Queue types. Old is used to assign a queue for use during change or delete operations. These operations may be derived to the same or to a different object hierarchy than the triggering class. That is, if a queue is not necessary during an insert.
26-5

26

Improving Rule Performance Changing the Execution Order for Target Objects

New is used to assign a queue for use during insert and change operations. These operations may be derived to the same or to a different object hierarchy than the triggering class. That is, if a queue is not necessary during a delete operation. Carried Old and Carried New are used when it is necessary to control queue inheritance as described below. Inheriting Queues Any derivation rules that are triggered and executed as a result of an update by a derived operation inherit the queue that was assigned to the derivation rule that initiated the chain reaction:

If a queue was previously defined for derivation 2, its value is added to the value of the inherited queue. Therefore, if derivation 2 was assigned a queue of 5, in the above example, derivation 2 is defined with a queue of 15 (10+5). Consequently you should be aware of the derivation chain that you are dealing with and not just the immediate derivation that you are defining with a queue. When you assign a queue to a derivation rule it is only inherited along the derivation chain to derivations that create derived operations to the same derivation queue (either to the internal queue or to the external queue). If you want to ensure inheritance from the internal queue to the external queue, define the queue using Carried Old or Carried New. The carried queue enables inheritance of a queue from a derived operation in the internal queue to a derived operation in the external queue. Example:

26-6

A carried queue can be defined without defining a queue, and vice-versa.

Chapter 27 Looping and Recursion

You can override the default restriction that prevents recursion. If a structure in the application allows for recursion, you can use rules to check and prevent the recursion. The following recursive situations must be prevented:

Single level looping Multiple level looping

27.1 Allowing Recursion Caused by a Derivation Rule

All the rulesets attached to a target object are triggered when: a derivation updates the target object the target object itself is updated Any derivation rules in these rulesets send messages to other objects and so on.

A derivation from a target object to any of the objects previously updated in the derivation chain is ignored:

27-1

27

Looping and Recursion Preventing Single-Level Data Looping

In addition to restricting looping to the same target occurrence, recursion to another occurrence of the same target (e.g. another occurrence of employee in Employee) is also prevented. You can override this restriction, to allow recursion.

To enable recursive derivations, from the Derivation Rule form (with the pointer in the Ruleset textbox) assign the Recursive option (Derivation category) to the derivation rules involved: You must assign the Recursive option to every derivation along the derivation chain that is involved in the recursion. For example, assigning the option to derivation 4 in the above diagram allows that derivation (to object 2) to be executed. The derivation to object 3 however will not execute since object 3 is already in the derivation chain, unless the Recursive option is also assigned to derivation 2. The same applies with derivation 3 (to object 4).

If you assign the Recursive option and you do not include a mechanism to stop the recursion (e.g. using a conditional rule), eMerge stops the looping automatically after a certain number of loops. (The number of loops is currently 150.)

27.2 Preventing Single-Level Data Looping

Single level looping can occur when the structure is such that a dependent object can point to the parent object:

Example
The parent is a project and the dependent is a subproject. The information about a subproject is the same as the information for a project. The key field of the dependent object is a pointer to the project description that is stored in the parent object. For example: Project 1: Order Entry
27-2

Looping and Recursion Preventing Single-Level Data Looping

Project 10: Customer Maintenance One of the subprojects of the order entry project is Customer Maintenance:

The information about Customer Maintenance is stored in the PROJECT object for customer maintenance. The SubProject object contains only one field: a pointer to the Project object. This pointer establishes the project hierarchy. Single level looping occurs when the subproject points to the parent project. For example:

Preventing Looping
Prevent this from happening by defining a validation rule which is executed whenever a subproject is inserted or changed. Use a validation rule like the following:
FIELDA must not be eq FILEDA of Parent.

Note the following: 1. Since the same key field (Fielda) is used in both the parent and the dependent, the field in the parent must be qualified (with the OF PARENT clause) to distinguish between the two fields.

For additional clarity the field in the triggering object could also have been qualified in the same way (Fielda of DEPENDENT).

2. The rule is triggered for an insert or change operation and not for a
27-3

27

Looping and Recursion Preventing Multiple-Level Data Looping

delete operation. This is the default when executing a validation rule.

27.3 Preventing Multiple-Level Data Looping

Multiple level looping can occur with the same structure described above (i.e. a dependent object can point to the parent object):

Physical Structure Showing Looping

Logical Structure Showing Looping

Multiple level looping occurs when a subproject points to a parent project in the project chain.

Preventing Looping via a Validation Rule

There are a number of ways to prevent this kind of looping. The simplest is to include a validation rule to insure that the key value of the

27-4

Looping and Recursion Preventing Multiple-Level Data Looping

dependent object must always be greater than the key value of the parent object. Thus all looping is prevented (including single level looping. Use a validation rule like the following:
FIELDA must be gt FIELDA of parent.

If this restriction is not possible you need to prevent looping as follows.

Preventing Two Level Looping

Preventing the parent object of the current parent object from being the same as the current triggering object. Example: As in the example above, the parent is a project and the dependent is a subproject. To prevent two level looping define a fetch rule which is executed whenever a subproject is inserted or changed. The fetch rule accesses the parent of the triggering objects parent object. If the fetch is successful, looping has occurred. To prevent the looping another ruleset is called which includes a validation rule which fails. If the fetch is not successful, processing continues (i.e. looping did not occur). Use an fetch rule like the following:
use FIELDA is path FIELDA of parent is targetkey then call REJECT.

Note the following: 1. Since the same key field (Fielda) is used in both the parent object and the dependent object, the field in the parent must be qualified (with the OF PARENT clause) to distinguish between the two fields.

For additional clarity the field in the triggering object could also have been qualified in the same way (Fielda of DEPENDENT).

2. The rule is triggered for an insert or change operation and not for a delete operation. That is, the NotOnDelete option (OnOperation category) is assigned (in addition to the default Fetch option). 3. The CreateThen option (Create category) is assigned to generate the called ruleset (Reject) automatically. On compilation the option is removed. For additional details see "Other Methods to Create a Call Rule" on page 20-5. 4. Looping occurs if the fetch is successful. If the fetch fails it means that looping did not occur and processing should continue. Assign the IgnoreMissingTarget option (Access category) to the rule. This results
27-5

27

Looping and Recursion Preventing Multiple-Level Data Looping

in continued processing even after the fetch fails (assuming no subsequent call exists within the ruleset). 5. The Reject ruleset includes a single validation rule that always fails. See "Ensuring that a Check Fails" on page 18-18 for details of this kind of check.

Preventing Higher Level Looping

Preventing looping in a chain above the grandparent level requires finding all the parents up the chain and checking each one against the current value being inserted. This requires a number of repeated fetches to scan the object occurrences at each level of the chain. Because of the I/O overhead involved, eMerge restricts the number of repeated fetches allowed and the number of nested fetches allowed. If looping to this extent is possible, consider other alternative designs. For example:

Imposing a limit on the number of levels. Imposing restrictions on the numbering system (e.g. a subproject number has to be bigger than the parent project number).

27-6

Chapter 28 Additional Rule Features

Rules includes a number of features that are needed only in specific circumstances, in an application. Some of these features are described below:

Calling a ruleset, where the ruleset is determined dynamically at the time of the call. Limiting which objects can cause a rule to be executed. Controlling which set of values is used by a rule. Automatically triggering rules attached to dependent objects that reference a field in the triggering class.

28.1 Dynamically Calling a Ruleset

You can set up a call rule so that the ruleset that is called is determined dynamically at the time of the call. The call to this ruleset is termed a dynamic call. When an unconditional dynamic call is made, the number of the ruleset called is taken from the THEN RULESET global field. When a conditional dynamic call is made:

If the condition is met, the number of the ruleset called is taken from the THEN RULESET global field. If the condition is not met, the number of the ruleset called is taken from the ELSE RULESET global field.

Example: In an employee application, you need different rulesets for the different tax brackets of the employees. During the monthly salary run you want to be able to call dynamically the correct ruleset for each employee based on the employees gross salary.

28-1

28

Additional Rule Features Dynamically Calling a Ruleset

Writing the Rule Text

In the rule text for the rule, include the following:

A call to the DYNAMIC PROCESS ruleset. This ruleset calls the rule whose number is stored either in the THEN RULESET global field or the ELSE RULESET global field. The THEN RULESET global field is used for unconditional calls and also for the then ruleset in a conditional call (when the condition is true). The ELSE RULESET global field is used for the else ruleset in a conditional call (when the condition is false).

1 Define a rule that stores the ruleset numbers in the THEN RULESET and ELSE RULESET global fields.

You do not need to specify that the THEN RULESET and ELSE RULESET fields are global fields.

Example: To determine the necessary ruleset to be called, based on the employees status, use a computation rule like the following:
THEN-RULESET is computed as EMPLOYEE-STATUS + 330000.

2 Define the call rule to the DYNAMIC PROCESS ruleset. Example: Use an unconditional call rule, like the following, to call the appropriate ruleset:
call DYNAMIC-PROCESS.

The computation and call rules (in steps 1 and 2) replace the following conditional call rules:
If If If If employee-status employee-status employee-status employee-status = = = = 1 2 3 4 then then then then call call call call #330001 #330002 #330003 #330004 ...

If the call is conditional, use a call rule like the following:

if <condition> then call DYNAMIC-PROCESS else call DYNAMIC-PROCESS.

In the example, when <condition> is true, the call to DYNAMIC-PROCESS calls the ruleset whose number is stored in the THEN RULESET global field.

28-2

Additional Rule Features Using Dynamic Calls

When <condition> is false, the call to DYNAMIC-PROCESS calls the ruleset whose number is stored in the ELSE RULESET global field.

28.2 Using Dynamic Calls

The following tips should be considered when using dynamic calls as part of your application.

Ensuring that the Rule Context is Correct

Both the THEN RULESET and ELSE RULESET fields are defined as global fields. Global fields are always in rule context and a value defined by another user, or by another operation, which has no connection to your needs, is available in the rule context until you override it with the values you require. Therefore, you must ensure that the correct values are defined to these fields before they are used. A global value is available, based on the operating system, as follows: CICS IMS For the server in which it was defined. For the same MPP region in which it was defined. For the same user for which it was defined.

TSO or CMS Batch

For the same job for which it was defined.

In addition to ensuring that the correct values are entered into the THEN
RULESET and ELSE RULESET global fields before they are used, ensure that

other fields in rulesets that are called dynamically are also in the rule context, before the ruleset is called. Use another ruleset to ensure that all the relevant field are in the rule context (use the "<field> IS TRIGGER" clause in a rule where necessaryrefer to details of the triggering field syntax in the General Reference).

Ensuring that the Nested Rulesets Exist

Ensure that the rulesets which are called dynamically have not been deleted. Normally, a nested ruleset has a source ruleset (the calling ruleset). eMerge establishes cross-references between the calling and called rulesets preventing deletion of the nested rulesets. Rulesets which are only called dynamically have no source rulesets and, consequently, there are no cross-references. Therefore, you can delete these rulesets

28-3

28

Additional Rule Features Using Dynamic Calls

without receiving any messages (error or warning) that the rulesets are still in use.

Nesting Rulesets Called Dynamically

Avoid nesting rulesets that are called dynamically in the following cases:

The dynamic call is part of a repeated fetch rule, where one of the rules in the called ruleset recomputes the values of the THEN RULESET field. The ruleset that includes the dynamic call is itself called (recursively) by a rule in the called ruleset, after the values of the THEN RULESET and ELSE RULESET fields have been recomputed.

In both of these cases the initial value is replaced before the ruleset is reexecuted, resulting in an error situation.

Initialization for Dynamic Calls

If you include a dynamic call, the following can happen. The first two situations result in continued processing. The last two result in an error.

The call is to the required ruleset you defined in the THEN RULESET or ELSE RULESET fields. The call is to a ruleset which does nothing. A value is not defined to the THEN RULESET and/or ELSE RULESET fields, and a dynamic call is made. eMerge attempts to call 0 (the default value). This results in an error, since ruleset zero does not exist. A value that you do not want was defined (e.g. by another user) for the THEN RULESET and/or ELSE RULESET fields. This results in an error, since the wrong ruleset is called.

By initializing the THEN RULESET and ELSE RULESET fields via a separate computation rule or by a condition in the call rule, you can control the outcome of the dynamic call in all situations: Initialization for Continued Processing Initialize the THEN RULESET and ELSE RULESET fields by assigning a value of one. No additional processing is done via this called ruleset and processing continues.

THEN-RULESET is computed as 1 ELSE-RULESET is computed as 1.

28-4

Additional Rule Features Old and New Values Affecting Dynamic Calls

if <condition> then THEN-RULESET is computed as EMPLOYEE-STATUS + 330000 else THEN-RULESET is computed as 1.

Initialization for Stopping Processing

Initialize the THEN RULESET and ELSE RULESET fields by entering a value of zero. An error results and processing stops (the call is to a nonexistent ruleset). Entering a value of zero is not the same as relying on the default value of zero, since this value might have been overwritten (e.g. by another user).

28.3 Old and New Values Affecting Dynamic Calls

During rule processing of an object occurrence, eMerge makes use of either or both of two sets of values: the values stored in the occurrence before the update (old values) and the values after the update (new values). The following table shows what values are used depending on the operation: Operation insert change delete new values old values or new values old values Possible values used

When both old and new values are used, there can be two passes (once with the old values and once with the new values). See "Controlling the Values Used by a Rule" on page 28-7 for details. The DYNAMIC PROCESS ruleset is called, in a change operation, only once. It is called using the old values of the THEN RULESET and ELSE RULESET fields. To use the new values, either assign the NoOldCall option or compute the THEN RULESET and ELSE RULESET fields as constants.

If you use the FROMOPER keyword in a rule, only the operation values are in the rule context, not the old values (from the constructor).

28.4 Limiting the Objects Causing Rule Execution

You can allow a rule to be executed or ignored based on which objects were updated in the derivation chain prior to the rule being triggered.

28-5

28

Additional Rule Features Limiting the Objects Causing Rule Execution

Example: In a payroll application part of the payment includes benefits. Contract employees do not receive the same benefits as permanent employees. However, you want all the benefit payments to be calculated in the same ruleset. The monthly salary updates to Payment come from either Permanent Detail (containing information about permanent employees) or from Contract Detail (containing information about contract employees). Once updated a series of computation rules are executed to increase the payment for the employee by the benefits. Those benefits that contract employees are not entitled to are marked so that they are not executed:

The source object can be any object in the derivation chain. Stipulating the object nearest to the object with the rules to be ignored is recommended. That is, from the above diagram you should designate Permanent Detail and not Object A as the source object. You can specify that the rule be ignored when the specified source object is in the derivation chain, or that the rule be executed when the constructor is in the derivation chain.

If you specify the objects which can trigger a rule, as opposed to those which cannot, you must remember subsequently to include any new objects in the list of source objects. However, the decision of how to specify should be based on the consideration of the majority of cases. That is, if the rule should normally be executed, then specify only exceptions. Conversely, if the rule should normally not be executed, specify the objects which can trigger it.

28-6

Additional Rule Features Controlling the Values Used by a Rule

To specify a source for a rule: The source objects are identified by their underlying composite and class definitions.

1 From the rule model select the rule for which you which to specify a source. Select Object Rule Definition. The rule definition form for the particular rule is accessed (e.g. for a derivation rule: the Derivation Rule (200007) form, for a call rule: the Call Rule (200008) form, for a fetch rule: the Fetch Rule (200006) form). 2 Select the Source tab:

3 Specify the composite and class of the source objects. 4 To specify the objects which cannot trigger, assign the NotFrom option (When category) to the rule.

28.5 Controlling the Values Used by a Rule

During a change operation it is often necessary to relate both to the values currently existing in the database, old value (before the change) and to the new value (after the change) that is being entered into the database. Example: A part is ordered and the number ordered subtracted from the number in stock. If the number ordered is changed the following calculation must be performed using both the old (existing) values and the new values: Quantity in Stock Original order = 10 of A new_amount_1 = old_amount - 10 Updated order = 25 of A new_amount_2= new_amount_1 + 10 - 25 Example: eMerge optimizes performance such that if the change involves the same object occurrence the difference (15 in the example) is used. When this is not possible two calculations: the first to return to the
28-7

28

Additional Rule Features Triggering Dependent Rules Automatically

original situation and the second to make the change to the new situation: Quantity in Stock Original order = 10 of A new_amountA_1 = old_amountA - 10 Updated order = 25 of A amountA = new_amountA_1 + 10 new_amountA_2 = amountA - 25 If you want to maintain the old value, you must tell eMerge to ignore the old calculation. For example, the update includes a time stamp for the operation. The operation occurred (even if it was a mistake) and the time stamp is valid. Instead of reversing out the change, as if it didnt happen. you want to keep it and set a flag that the update wasnt valid.

Controlling Values Used by a Fetch or Derivation Rule

You can control which values are used by a fetch or derivation rule assign the IgnoreOld or IgnoreNew option (Target tab, Access category): 1 From the rule model select the fetch or derivation rule. Select Object Rule Definition. The particular rule definition form is accessed. 2 Select the Target tab. 3 Assign the IgnoreNew or IgnoreOld option (Access category) as required.

Controlling Values Used by a Call Rule

1 From the rule model select the call rule. Select Object Rule Definition. The Call Rule (200008) form is accessed. 2 Assign the NoNewCall or the NoOldCall option (Call category).

Only assign one option at a time from each pair (i.e. IgnoreNew or IgnoreOld, NoOldcall or NoNewCall).

28.6 Triggering Dependent Rules Automatically

When a dependent object references a field in a parent object, you can connect the field with the dependent object such that any change to the field triggers all the rulesets attached to the dependent object. The field in the parent object is referred to as a DownTrig field. Define a DownTrig field by designating the field as DownTrig in the rule:
28-8

Additional Rule Features Specifying a Site-Ruleset Based on Metadata Definitions

if FIELDA which is DOWNTRIG lt 1000 then

Any field which is designated as a DownTrig field is automatically included in the rule context and does not need fetching via a rule for the dependent object. All path fields are automatically designated as downtrig fields. Therefore, changing or deleting one of these fields in the parent object triggers the rules in the dependent objects.

The order that the rulesets attached to dependent objects are triggered is based on their object numbers, in ascending order.

28.7 Specifying a Site-Ruleset Based on Metadata Definitions

An on-site developer can specify a ruleset that is executed based on metadata/data definitions. This extends a core application by allowing the developer to fine tune the application to his needs. This is similar to a user exit in that it implements a specified ruleset after the core application rulesets are implemented. In this way a core application can be customized by adding rules to a ruleset to perform site-specific validations or to manipulate data values without affecting the core application rulesets. Site-specified rulesets can only have numbers in the range 9000000 to 999999. To enable Metadata Management the DBinDevelopment option must be assigned on the Database Standards form.

The effects caused by the site rules on the application are the sole responsibility of the site developer.

To specify a site ruleset:

1 From the navigation pane of Development Workbench, select the Logic tab. 2 Expand the Metadata Integration node and select Management. The Metadata Management form is displayed:

28-9

28

Additional Rule Features Specifying a Site-Ruleset Based on Metadata Definitions

3 Select a trigger from the Trigger Type listbox: Class Operation 4 Enter a value for the triggering object in the Triggering Object textbox. If the triggering type is Class, enter the Class No. If the triggering type is Operation, enter the Operation No. 5 Enter a value for the specific object that triggers the ruleset in the In Object textbox. If the triggering type is Class, enter the Composite No. If the triggering type is Operation, leave the textbox empty. 6 Enter a number for the site ruleset to be invoked by the triggering object in the Ruleset textbox. 7 Click OK.

28-10

Chapter 29 Debugging Rules

Tools are provided to help you check that application rulesets and rules behave as required:

The ruleset report facility The trace facility

29.1 Reporting About Rulesets and Rules

You can produce a report about all the rules in a ruleset or range of rulesets. The rulesets can be specific rulesets or all the rulesets attached to a specified triggering object:

The LISTRULESET Command

To produce the report enter the command in the Command box on the system toolbar.

29-1

29

Debugging Rules Reporting About Rulesets and Rules

Via the report you can check that the rules are as you want them per ruleset (e.g. certain rules are inactive, all the correct options are assigned etc.)

Example
To list the rules in RULESET 340001:

29-2

Debugging Rules Reporting About Rulesets and Rules

The output from the report is displayed:

Running a Report in Batch

The report can also be run in batch, using the Ruleset Report utility.

Sending Output to a Form

3270 Instead of producing a report, you can send the output to a form. From this form you can view the rules individually and make changes to them or add new rules to the rulesets.
LISTRULESET

To send the output to a form append the SCREEN keyword to the command.

29-3

29

Debugging Rules Reporting About Rulesets and Rules

The following form is displayed when the LISTRULESET 330010 command is entered with the SCREEN keyword:

From this form you can access the following forms:

The Ruleset Review form (via the RULELIST action). Each rule definition form (via the RULE-REV action).

29-4

Debugging Rules Tracing Ruleset and Rule Execution

29.2 Tracing Ruleset and Rule Execution

Use the trace facility to check how a rule behaves during its execution. You can trace all the rules triggered by an action or selected rules. The trace facility produces a report with the following details:

Ruleset being traced. Level of processing (each branch to a nested ruleset changes the level). Number of times the rule has been executed for a repeated rule. Operation code (Insert, Change or Delete, Edit) for the rule. The operation code can be different from the operation code of the initial operation. Rule being traced (the name and the type of the rule). Triggering object. Target data object (for a fetch rule and a derivation rule). Rulesets called from the current rule (for a call and a fetch rule). Values for all fields participating in a rule. Result of the rule execution.

29.3 Trace Output

Each rule is described on a new page of the report, with the exception of rules that are not executed. Rules that are not executed (e.g. validation rules during a delete operation, inactive rules) are still reported but on the same page as the following rule.

29-5

29

Debugging Rules Trace Output

L S A TRACE FOR RULESET:1-PROCESS EMPLOYEE (# 330010) PAGE:1 V E C L Q T 1 I OPERATION 10(CHECK)-CHECK AGE I FROM COMPOSITE:33,CLASS:33, I I PARTICIPATING FIELDS: FIELD FIELD I --------------------OLD VALUE NEW VALUE I WHEN CURRENT DATE (FLD 13) GE 12.03.2001 I (18.000 I X365.000 I ) I +BIRTH-DATE (FLD 3329) 07.12.1958 I (RESULT) 02.12.1976 I I NEW :COND TRUE. I *** END OF OPERATION:

LVL SEQ ACT FROM COMPOSITE FIELD OLD VALUE/ FIELD NEW VALUE NEW

Level. Repetitions (not shown). Operation code logic (Insert, Change or Delete) at instance of execution. Triggering object. Field values.

Results.

29-6

Debugging Rules Setting Rule Traces

29.4 Setting Rule Traces

For All Rules

To set the trace on:

1 Issue the TRACE RULE ALL command in the Command box on the system toolbar:

2 Press <Enter> to execute the command.

To set the trace off: Issue the TRACE OFF command in the Command box.

For Rules in a Particular Ruleset

1 Via the rule model, select the ruleset. 2 Click the Reports button on the toolbar or right-click the ruleset graphic symbol and choose ObjectReports. The Ruleset Reports menu is accessed:

29-7

29

Debugging Rules Setting Rule Traces

3 Choose the Trace On/Off option. The Ruleset: Trace On/Off form is accessed:

4 Assign or unassign the Trace Rule option as needed. 5 Click OK.

For Selected Rules

Via the Rule Model 1 Double-click the rule graphic symbol. The rule dialog box is displayed:

2 Assign the Trace option to the rule. 3 Click OK. 4 Repeat these steps for all the rules that you want to trace.

29-8

Debugging Rules Setting Rule Traces

5 Issue the TRACE RULES command in the Command box on the system toolbar. Via the Tree Control 1 From the Logic tab, expand the Ruleset node and then expand a ruleset under the node. 2 Right-click a rule under the ruleset and choose the Trace Rule On option:

3 Repeat these steps for all the rules that you want to trace. 4 Issue the TRACE RULES command in the Command box on the system toolbar.

Issuing the TRACE PATH command (with or without the ALL keyword) produces a report which does not include the values of the fields participating in the rules.

29-9

29

Debugging Rules Viewing Rules with Trace Option On

Setting Trace Off for a Range of Rulesets

1 Position the pointer in the rule model (not on a graphic symbol) and choose Model > Reports. The Ruleset Information menu is accessed:

2 Choose the Turn Off Trace option. The Ruleset: Turn Off Trace form is accessed:

3 Enter the From Ruleset No. and To Ruleset No. for which you want to turn off the trace option. 4 Click OK. The trace option for the indicated rulesets is turned off.

29.5 Viewing Rules with Trace Option On

You can view the rules in any or all of the rulesets that have the trace option on. 1 From the Tools tab, right-click the Development Tools node.

29-10

Debugging Rules Tracing Fetch Rules and Derivation Rules

2 Choose the Rule Information option. The Rule Information menu is accessed:

3 Enter the ruleset range for which you require trace information. Choose the All Rules with Trace On option. A list of the rules in the indicated rulesets with the trace option on is displayed.

29.6 Tracing Fetch Rules and Derivation Rules

To check how fetch and derivation rules behave during their execution according to their execution or definition order, issue one of these commands:

TRACE EX

Alternatively, you can use TRACE FETCH for fetch rules and TRACE DERIVE for derivation rules.

TRACE DEF

Issuing the TRACE EX or TRACE DEF commands produces a report with the following rule details:

Priority
29-11

29

Debugging Rules Tracing Fetch Rules and Derivation Rules

Level Triggering ruleset and class Type of updating Operation option Operation depth Field behavior and parameters Source and target composite and classes

Example
In this example, TRACE EX is used to detail and explain a fetch and derivation rule, the same information that could be deduced for each rule individually, via TRACE FETCH or TRACE DERIVE, respectively. The Fetch Birth Date (340013) rule:
EMPLOYEE-ID is path 1 is targetkey for CHILD-ID BIRTH-DATE #5014 is fetched.

and the Derive-Name (340014) rule:

EMPLOYEE-ID is path 2 is targetkey for CHILD-NAME SCLANG-NAME #5002 is moved to CHILD-NAME.

are attached to the Empl Error Overr (5024) operation. The Derive-Name (340014) derivation rule enters the selected Sclang-Name field for the child.

Structure of the Example Composite

The structure of composite 50 is displayed by entering this command: decode all;300,M,50
50 EMPLOYEE 11 @ 40 CLASS: 50 EMPLOYEE CLASS: 5010 CHILDREN CLASS: 5015 CHILDRENGRADE CLASS: 5020 PROJECT

29-12

Debugging Rules Tracing Fetch Rules and Derivation Rules

Structure of the Example Operation

Operation 5024 is displayed by entering this command: 400,M,5024
5024 EMPL ERROR OVERR 1 @ 11 FIELD: 5000 ID NO 7 8400 MOVE+MUST APP 5001 EMPLOYEE-NAME 20 8200 MOVE+MUST INS 5002 SCLANG NAME 20 5003 DIVISION NO 2 5004 BIRTH DATE 5 5005 SEX 1 5006 POSITION CODE 2 5007 SALARY 6 5008 HIRE DATE 4 TARGET Composite: 50 EMPLOYEE TARGET CLASS: 50 EMPLOYEE FORM: 502300 ERRORS-ALT. OPER 1 502400 ERRORS-ALT. OPER 1 502403 EMPLOYEE LIST 1 PRIVATE ERROR: 2010 20101 2000 LOW PRIOR 2014 20140 2020 20201 2233 22331 2000 LOW PRIOR 2838 28381 TRIGGER: 10 503500 FETCH BIRTH DATE 1

The TRACE EX Command

Enter trace ex;edit on; 5024,C,5024,,jean into the Command box on the system toolbar: trace ex Traces the execution of all derived operations and fetch operations, including the input operation according to the order in which they are executed. edit on Formats the output listing. Invokes the operation 5024 and inserts JEAN

5024,C,5024,,jean into the operation.

29-13

29

Debugging Rules Tracing Fetch Rules and Derivation Rules

Generated Listing for the Fetch Rule

See "Listing Fields" on page 29-16.
INTERNAL OPER ----------------------------------------------------------------------------|FIL|CLASS|OPERA | |FROM |UPD |SAM4| | |LER|499 |TION |OPERATION NAME |CLASS |A T |99 |DEPTH | | | |NO. | | |YPE | | | ----------------------------------------------------------------------------| 0 | | 1 | FETCH BIRTH-DATE FROM SON | 5010 | 0 | 0C | 1 | | | | | | | | | | | | | |NO OF CLASS 1 RESPONSIBLE 5024 |RULE NO. 10 | | | | | | ------------------|-------| | | | | | RULESET NO. 503500 | | | | | | | | | ----------| | | | | -----------------------------------------------------------------------------

INTERNAL OPER --------------------------------------|FIELD |INPUT|CHECKSET |CHECKSET| |NO. |LENGT|OPTION-A |OPTION-B|VALUE | |H | | | --------------------------------------| 5000 | 4 | 0020 | | 5024 | | 5010 | 4 | 8000 | | 1 | ---------------------------------------

| | |

TARGET COMPOSITE ---------------------------------------|COMPOSITE |CLASS|OPER |DIRECTI |TARGET | |NO. |NO. |CODE |NG CLASS |CHECKSET| | | |COL | |OPTIONS | ---------------------------------------| 50 | 5010 | 0 | 0 | 0001 | ---------------------------------------SOURCE ----------------|COMPOSITE|CLASS| |NO. |NO. |

29-14

Debugging Rules Tracing Fetch Rules and Derivation Rules

----------------| 50 5010 | -----------------

Generated Listing for the Derivation Rule

See "Listing Fields" on page 29-16.
INTERNAL OPER ----------------------------------------------------------------------|FIL|CLASS|Opera | |FROM |UPD |SAM4| | |LER|499 |TION |Operation NAME |class |A T |99 |DEPTH | | | |NO. | | |YPE | | | ----------------------------------------------------------------------| 0 | | 1 | DERIVE CHILD-NAME | 50 | 1 | 08 | | | | | | | | | ----------------------------------------------------------------------INTERNAL OPER ----------------------------------------------------------------------|FIL|CLASS|Opera | |FROM |UPD|SAM4| | |LER|499 |TION |OPERATION NAME |class |A T|99 |DEPTH | | | |NO. | | |YPE| | | ----------------------------------------------------------------------| | | | DEPTH 1 NO OF Class 1 RESPONSIBLE 5024 RULE NO. 10 | | | | -----------------------------| | | | PROCESS NO. 503502 | | | | | | | | ----------| | | | -----------------------------------------------------------------------

INTERNAL OPER --------------------------------------|FIELD |INPUT|CHECK |CHECK | | |NO. |LENGT|SET-A |SET- |VALUE | | |H | | | | --------------------------------------| 5000 | 4 | 0020 | | 5024 | | 5010 | 4 | 8000 | | 2 | | 5011 | -1 | 8000 | | JEAN | --------------------------------------29-15

29

Debugging Rules Using a Trace Path

TARGET COMPOSITE ---------------------------------------|COMPOSITE |CLASS|OPER |DIRECTI|TARGET| |NO. |NO. |CODE |NG SEG |CHECK | | | |COL | |SET | ---------------------------------------| 50 | 5010 | 0 | 0 | 0001 | ---------------------------------------SOURCE ----------------|COMPOSITE |CLASS| |NO. |NO. | ----------------| 50 | 50 | -----------------

Listing Fields
CLASS 499 FROM CLASS UPDATE TYPE SAM 499 DEPTH NO OF CLASS RESPONSIBLE CHECKSET OPTIONS Priority specification. From which class is the triggering ruleset derived. The operation type, coded as follows: Insert (Edit) 0; Change 1; Delete 8. Rule type indicator with the following values: x'08' - derivation (including the original user Operation) x'0C' - fetch x'8C' - repeated fetch Number of levels down being updated (here, one class). Number of classes to be updated (here, one). The path key, as depicted in the following internal operation. Operation options: PATH (A:0020) and MOVE (A:8000).

29.7 Using a Trace Path

Usage of TRACE PATH outputs an overview of the ruleset. Continuing with the example on "Tracing Fetch Rules and Derivation Rules" on page 29-11, entering the same operation with a trace path request (trace path all;5024,c,5024,,jean) yields the following listing:
29-16

Debugging Rules Deactivating Rulesets and Rules

L S A TRACE FOR RULESET:1-FETCH BIRTH DATE (# 503500) PAGE:1 V E C L Q T 1 I OPERATION 10(FETCH)- FETCH BIRTH-DATE FROM SON I FROM OPERATION:5024, (ONCHANGE)TO COMPOSITE:50,CLASS:5010. I *** END OF OPERATION:STOPPED BECAUSE AN ERROR WAS FOUND.

LVL SEQ ACT FROM OPERATION (ONCHANGE) TO COMPOSITE:50 CLASS:5010

The nesting depth of other rulesets to which this rule calls. The order placement in a repeated (sequential) rule. Operation code logic (Insert, Change or Delete) at instance of execution. Where the trigger was activated from. Rule options. Target class of the rule.

29.8 Deactivating Rulesets and Rules

By selectively making some of the rulesets and/or rules inactive, you can narrow down the number of rules that need checking. Making a ruleset inactive makes all the rules in the ruleset inactive. Making a rule inactive is limited to the specific rule. Make the rulesets and rules inactive in conjunction with the trace facility to help debug an application.

Remember to assign the Active option after the ruleset have been checked.

29-17

29

Debugging Rules Deactivating Rulesets and Rules

For a Ruleset
Via the Rule Model 1 Double-click a ruleset graphic symbol. The ruleset dialog box is displayed:

2 Unassign the Active option. 3 Click OK. Via the Tree Control 1 Expand a triggering object (e.g. a class within a composite):

29-18

Debugging Rules Deactivating Rulesets and Rules

2 Right-click a ruleset (i.e. a trigger) and choose the Assign Inactive to Trigger option:

For a Particular Rule in a Ruleset

Via the Rule Model 1 Double-click the rule graphic symbol. The rule dialog box is displayed:

2 Unassign the Active option. 3 Click OK.

29-19

29

Debugging Rules Deactivating Rulesets and Rules

Via the Tree Control 1 From the Logic tab, expand the Ruleset node and then expand a ruleset under the node. 2 Right-click a rule under the ruleset and choose the Assign Inactive to Rule option:

29-20

Chapter 30 Handling Errors

If an error occurs, eMerge displays an error message. The full list of errors, along with explanations of the errors can be generated via the Error Report utility. When you receive an error you can display further details about the error by entering a question mark (?) in the Command textbox located on the Development Workbench toolbar. The original error is redisplayed and, after clicking OK to clear the error, any additional information is displayed. For an error situation in an application, you can do the following:

Display the existing eMerge error message. Display a different message. Branch to another form to resolve the error. Form Operation Rule (derivation rule or fetch rule only) Field

You can replace an existing message at the following levels:

The field level is the lowest level and occurs whenever an error situation arises that includes the field. The rule level occurs if the error resulted from executing a rule, irrelevant of which operation or form caused the rule to be executed. The operation level occurs if the error resulted from issuing the operation, irrelevant of the form that includes the operation.

30.1 Displaying an Existing eMerge Message

Standard messages are issued for any error that occurs, unless the error occurred while running a validation rule or fetch rule. In the case of a validation rule or fetch rule, you define the error message that is displayed as part of the rule definition. You do not need to specify

30-1

30

Handling Errors The ERROR DETAILS Command

an error message for a fetch rule. If you dont, eMerge generates an appropriate message.

30.2 The ERROR DETAILS Command

Use the ERROR DETAILS ON command to obtain details on the source of an error. When the ERROR DETAILS ON command is issued, the following is automatically added to the text of the error message:

For all errors, the DBID (Database ID) is added to the text of the error message. When an error occurs during the execution of a rule, or during an invoked operation, the following additional information is added to the text of the error message: ruleset number rule number When an error occurs during batch processing, the line number is added to the text of the error message. When an error occurs during batch file processing for a batch file created by the Journal Extraction utility, the internal journal sequence number is added to the text of the error message.

30.3 Displaying a Different Message

Instead of displaying the eMerge message you can display a different message by performing these two steps:

A new message must be defined containing new message text to replace the eMerge message text. This new message is identified by a message number. The new message text can include values contained in fields in the database (internal fields). An override definition for the eMerge error message number must be specified that instructs the system to substitute the new message number for the eMerge message number that would normally be issued when encountering the particular error.

Once these steps are completed the new message is displayed instead of the eMerge message.

30-2

Handling Errors Displaying a Different Message

Restrictions on Message Substitution

Not all eMerge messages can be replaced by a different message. This table lists the ranges of eMerge errors that can be replaced and any restrictions imposed on the range: System Error 1-999 1000-2399 2400-2499 2500-2799 2800-2999 3010-3020 3500-3599 6100 6119 6121 6208 6230 Cannot be replaced. Cannot branch automatically to another data entry form (i.e. a return action is not allowed). Cannot branch automatically to another data entry form (i.e. a return action is not allowed). Alternative errors (displayed when eMerge privacy is set) must be assigned the MayRecover option. Restrictions Only with the MayRecover option.

Error Substitution under Privacy

If privacy is used, some eMerge error messages are replaced by alternate errors. Even though the alternate error messages are displayed, if you want to replace the message, you must relate to the original error. The following table lists the errors involved, showing the error number you see and the original error number that you must use when reassigning the error: Displayed Error 2020 2035 2047 2130 2132 2134
30-3

Original Error

30

Handling Errors Displaying a Different Message

Displayed Error 2048 2049 2060 2072 2111 2120 2160 2840 2136 2138 2140 2142 2144 2146 2141 2864

Original Error

Error Options that Prevent Message Substitution

If any of the following options are assigned to an eMerge error, it cannot be replaced by a user defined error. Refer to the Form Reference (the Error Definition form) for details of these options.

MemoryRefresh ImmediateAbend AbendBeforeError SystemAnalystError DeveloperError DBA-Error DBD-Error

30-4

Handling Errors Displaying a Different Message

Defining the New Message Text

Create new message text as follows: 1 From the Logic tab choose Errors New Error.

2 Enter a number for the error in the Error field. You can define errors with a number in the range 20000 to 29999. Once you have defined the error you can use it to replace an existing eMerge error. You cannot assign any options for the message. When you replace an eMerge message with a new message, any options assigned to the eMerge message also apply to the new message. 3 Enter the text of the message in the Error Line fields. Include field values in the error message if necessary. See "Including Field Values in an Error Message" on page 30-6.

30-5

30

Handling Errors Displaying a Different Message

Including Field Values in an Error Message

Values stored in the database can be included in the message by specifying their internal field number as part of the message. The internal field number to be used as part of the message is entered into the Internal Field field. You must break up the text so that the internal fields are positioned correctly in the message. An internal field value used in a message appears at the end of the current error line. Internal Field Meanings List of Internal Fields To see the meaning of a particular internal field zoom on the field to display the Field Definition form and then click the Values button. To see the list of all the Internal Field values with their names and other information about them, enter EDIT ON and then 1020,l (i.e. list all the occurrences of operation 1020) into the Command textbox.

Example of Error Message Substitution

The following message is defined in eMerge:

30-6

Handling Errors Overriding an Error Message

If an error occurs that causes this message to be displayed, the user sees the following message, where the text between angle brackets is the value of the internal field.
Deleting (or changing the KEY) of <name of class> is not allowed because it includes at least one <name of dependent class> occurrence.

Note the way the text of the message is split to allow the internal field values to be included in the right positions.

30.4 Overriding an Error Message

A substitute error can be defined to override a system error on the form, operation or rule levels. The substitute error message text is then displayed instead of the system error message text. There are two ways to define a substitute error: Via the Error Message tabpage on the Rule Definition form (e.g. for fetch and validation rules). See "Overriding an Error Message via the Error Message Tabpage" on page 30-7. Via the Error Override tabpage on the form, operation, or rule level (e.g. for fetch and derivation rules). See "Overriding an Error Message via the Error Override Tabpage" on page 30-8.

A substitute error defined at the rule level via the Error Message tabpage on the Rule Definition form has the highest override priority.

Overriding an Error Message via the Error Message Tabpage

The following describes how to set up error override for a fetch or validation rule via the Error Message tabpage on the Rule Definition form. If an error is generated while executing the rule the substitute error message is displayed. The priorities for error message substitution listed for error overrides defined via the Error Override tabpage are not in effect for error overrides defined via the Error Message tabpage. A substitute error message defined via the Error Message tabpage takes priority over any substitute errors defined on the form or operation level (even without assigning LowPriority at the form or operation level). You can change the priority by assigning LowPriority on the rule levelthen the form or operation has higher priority. 1 Access the Rule Definition form for the specific rule for which you want to define a substitute error.
30-7

30

Handling Errors Overriding an Error Message

2 Select the Error Message tabpage. 3 Enter the error message text in the Message textbox. 4 Enter the number of the substitute error in the Substitute Error textbox.

Overriding an Error Message via the Error Override Tabpage

The order of priority for displaying error messages that are defined at more than one level is: form, operation and then rule. You can override this ordering by assigning the LowPriority option. See "Changing Priorities for Displaying Messages" on page 30-10. The following describes how to access the appropriate error override form for a form, operation or rule, and how to set up error override. Except for the title, the error override forms are identical. Accessing Error Override for a Form 1 From the model, right-click the graphic symbol for the implemented concept to which the rule is attached. 2 Select Object Concept Design to access the Concept: Design form. 3 Right-click with the pointer in the Design textbox, and select Forms from the pop-up menu that is displayed. The Constructor Forms (100193) form is displayed. 4 Right-click with the pointer in the Single or Multi textbox and select Detail from the pop-up menu that is displayed. The Form Definition form is displayed.

30-8

Handling Errors Overriding an Error Message

5 Select the Error Override tabpage:

Accessing Error Override for an Operation 1 From the model, right-click the graphic symbol for the implemented concept to which the rule is attached. 2 Choose Object Concept Design to access the Concept: Design form. 3 With the pointer in the Design textbox, right-click and select Operation from the pop-up menu that is displayed. The Constructor: Operation Definition form is displayed. 4 Select the Error Override tabpage:

30-9

30

Handling Errors Overriding an Error Message

Accessing Error Override for a Rule

To replace an existing fetch or derivation rule error message:

1 From the rule model, select the rule and click the Rule button. The rule definition form is displayed. 2 Select the Error Override tabpage:

Replacing an Error Message for a Form, Operation or Rule

Except for the level (form, operation or rule) the error override forms are similar.

1 Enter the number of the eMerge message to be replaced in the System Error field. 2 Enter the number of the error to replace the eMerge error in the Subs. Error field. If you have not yet defined the substitute error, select the Substitute Error field and right-click in the field, a pop-up menu is displayed. Select Detail. The Error Definition form is displayed. Define the substitute error and click the OK button to return to the error override form. 3 Choose the Context Class and Context Field. Changing Priorities for Displaying Messages If a user message is defined at the form level, even if a message is also defined at the operation level (for the same error context) or at the rule level (also for the same error context), the form level message is displayed. The default priority behavior for displaying error override messages is therefore: form, operation, rule.

30-10

Handling Errors Invoking a Ruleset Whenever an Error is Issued

To change the priority, assign the LowPriority option via the Error Override tabpage for the form so that the message defined at the operation level (or in absence of the operation level the message defined at the rule level) is displayed instead of the form level message. Example: When LowPriority (Advanced category) is assigned via the Error Override tabpage for an operation, if a form level definition exists, the form level has priority (i.e., the default priority behavior is in effect). However, if a rule level message exists for the same error case, and a form level does not exist, the rule level message is used (i.e. the priority is changed).

30.5 Invoking a Ruleset Whenever an Error is Issued

When working in batch, you can invoke a particular ruleset anytime an error is issued. The particular ruleset that is invoked is determined via the RULESET ON ERROR command. The ruleset can use the global fields: Error from Ruleset (the number of the ruleset that most recently issued an error) and Error from Rule (the number of the rule that most recently issued an error). Errors 2675, 2676, 3003, and 7000 do not invoke the ruleset.

30.6 Replacing a Message Based on an Internal Field Value

A user error can be defined that contains a user message that replaces (substitutes) an eMerge error message. The user defined error message can contain internal fields. A ruleset can be defined by the user, that is triggered by the user defined error. The triggered ruleset can have rules that contain messages dependent on the value of the internal field used in the triggering user defined error message. In this manner, different user error messages can be displayed, dependent on the value in the internal field used in the users substitute error message.

Dynamic Error Message Substitution

1 Define an error message that is used to replace (substitute) the system error message via the Error Definition form. See "Defining the New Message Text" on page 30-5.

30-11

30

Handling Errors Replacing a Message Based on an Internal Field Value

2 Assign this error as the substitute error to override the eMerge system error via the appropriate error override form (form, operation or rule). 3 Define an error ruleset that is triggered by the user substitute error. The error ruleset is triggered when a user defined error is issued. 4 The triggered error ruleset returns the value of another user defined error. The number of this additional user defined error is placed in a global field called RETURNED ERROR via a conditional computation rule (that is a rule in the triggered ruleset). The system uses the value in the RETURNED ERROR field as the number of the error to display.

Flow of Dynamic Error Message Substitution

30-12

Handling Errors Replacing a Message Based on an Internal Field Value

Example of Dynamic Error Message Substitution

The following example shows the flow for defining an error to replace an SQL error which is returned when referential integrity is violated using DB2 to store the application data: 1 Define a substitute error message to replace the eMerge system error message. See "Defining the New Message Text" on page 30-5.

This user defined error message uses an internal field (23288) that contains the value of an SQL error. (Based on the SQL error value different user error messages can be displayed.) 2 Assign the user error message as the substitute error for the system error 3517 that deals with SQL codes. Use the appropriate error override

30-13

30

Handling Errors Replacing a Message Based on an Internal Field Value

tabpage (form, operation or rule), see "Overriding an Error Message" on page 30-7). For example for an operation:

The text of the new error (23519), the error options, and the internal fields used in it, are the same as for the original error (3517). 3 Define a ruleset that is triggered by the user defined error (23519). Access the Ruleset Definition form. Fill in a number and name for the ruleset.

30-14

Handling Errors Replacing a Message Based on an Internal Field Value

4 Select the Triggering Objects tab. Click the OtherTrigger button. The Triggering Objects form is accessed. Fill in the number of the triggering error (23519) that triggers the ruleset:

5 Access the Error Definition form and define an additional user defined error message (e.g. error number 23520) that you want to be displayed when the an SQL error of -530 is encountered by the system:

30-15

30

Handling Errors Branching to Another Form

6 Define a conditional computation rule for the SQL ruleset (351709) that places the number of the additional user defined rule (23520) in the RETURNED ERROR global field based on the value located in the internal field (23288) (i.e. based on the SQL error code issued):
if #23288 =-530 the RETURNED-ERROR is computed as 23520.

The RETURNED ERROR global field is used to store the value of the user defined error message to be displayed. If the value of the internal field 23288 is -530 (an SQL error code), the returned error that is displayed is 23520.

Only computation, call, validation and fetch rules can be defined. Validation or fetch rules that include an error message, a returned action, a substitute error or the Warning option cannot be defined.

When running the application, if error code 3517 is encountered, it is replaced by error code 23519. This triggers the ruleset (351709) which results in the error code 23520 being displayed (if the condition in the computation rule is met, i.e. the SQL code is -530). In practise, when a user tries to enter a value for a supplier in an order, where the supplier is not defined in the corresponding Suppliers constructor an error is displayed. Different error messages can now be defined, via a series of computation rules in the triggered ruleset, for different SQL codes.

30.7 Branching to Another Form

If the solution to the error situation involves using a private action (button), you can cause eMerge to execute the private action automatically. You can branch to another form at the following levels: Form Operation The operation level occurs whenever an error occurs with the operation, irrelevant of the form that includes the operation. Rule The rule level occurs if a rule caused the error, irrelevant of which operation or form caused the rule to be executed. Field The field level is the lowest level and occurs whenever an error situation arises that includes the field.

30-16

Handling Errors Branching to Another Form for a Form, Operation or Rule

30.8 Branching to Another Form for a Form, Operation or Rule

The order of priority for branching to another form for errors that are defined at more than one level is: form, operation and then rule. You can override this ordering by assigning the LowPriority option. See "Changing Priorities for Displaying Messages" on page 30-10.

Branching to another Form

1 Access the appropriate error overriding tab. See "Overriding an Error Message" on page 30-7. 2 Enter the number of the eMerge error that causes the error in the System Error field. 3 Enter the number of the error to replace the eMerge error in the Subs. Error field. 4 Enter the number of the form action in the Action field. The private action must be defined in the form where the error occurs (or every form where the error can occur if the branch is for the operation or rule). When you branch to another form on receiving an error, you can either display the error message, display the error message along with another message stating the form where the error occurred (a source message), or if the error is obvious, suppress the display of the message.

Display a Source Message along with an Error Message

Assign the SourceMessage option (Advanced category) in the relevant error override form (form, operation or rule).

Suppressing an Error Message

Assign the Suppress option (ErrorOverride category) in the relevant error override form (form, operation or rule). You can only suppress the display of an eMerge error message. If the number of the error is in the range 1000-2799, a branch to another form must be defined (via the Action field).

30-17

30

Handling Errors Branching to Another Form for a Field Value

If the number of the error is in the range 2800-3020, the MessageOnly option must be assigned to the error (in the Error Definition (101060) form).

Example
An error occurs because a value entered in a form does not exist in the subject constructor. The error can result in the subject constructor data entry form being accessed to immediately allow the relevant details to be added. The following form shows two errors that can occur for the employee (330000) form. If either error situation occurs, a branch to another form occurs. The first error message is suppressed. The second error is a user defined error message:

30.9 Branching to Another Form for a Field Value

Branching to another form, based on the contents of an internal field, requires rules. The basic method is the same as described in "Replacing a Message Based on an Internal Field Value" on page 30-11, except that an action is returned. To return an action use the RETURNED ACTION keyword in the rule statement. The ruleset is triggered when a user defined error is issued. The error ruleset returns the value of an action which is automatically executed to access another form where the problem can be resolved. You replace the system error message with the user defined error message that is used to trigger the ruleset at either the form, operation or rule level. All the rules that apply to replacing error messages at any of these levels also apply in this case. See "Overriding an Error Message" on page 30-7.

30-18

Handling Errors Branching to Another Form for a Field Value

Flow

Example
The following example shows the flow for defining an action to replace an SQL error which is returned when referential integrity is violated using DB2 to store the application data. The steps are identical to those listed in "Replacing a Message Based on an Internal Field Value" on page 30-11 except for the conditional computation rule used in the triggered ruleset:
if #23288 is =-530 RETURNED-ACTION is computed as 24.

The RETURNED ACTION global field is used to store the value of the action. If the value of the internal field 23288 is -530 (an SQL error code), the returned action that is executed is PF24.

Only computation, call, validation and fetch rules can be defined. Validation or fetch rules that include an error message, a returned action, a substitute error or the Warning option cannot be defined.

While running the application, if error code 3517 is encountered, it is replaced by error code 23519. If the condition in the computation rule is met (i.e. the SQL code is -530), the ruleset is triggered and results in the returned action being executed. In practise, when a user tries to enter a value for a supplier in an order, where the supplier is not defined in the corresponding Suppliers constructor, the supplier form is displayed, allowing the user to enter the supplier details.

30-19

30

Handling Errors Branching to Another Form for a Field Value

Different error messages can now be defined, via a series of computation rules in the ruleset, for different SQL codes. The different rules can return another error message code or action or both.

Obtaining Business Integrity Server Error Message Information via a User Exit
A user exit can access Business Integrity Server error message information. This allows non-eMerge tools access to Business Integrity Server error message information. The following are some of the error message information available:

error class error type error severity error number error text

A folder named MessageExit (pointed to from the Adapter folder) contains entries which give information about the message user exit. The following entries are available in the MessageExit folder: Entry Name ExitActive RoutineName ExitParameters Explanation Indicates if the user exit is active. The name of the user exit routine. Valid Values YES - The user exit is active. NO - The user exit is not active. 8 uppercase alphabet characters.

Information exposed to the user exit Any character string. in the form of a character string. A string describing user parameters, e.g. SOCKET NUMBER = 5, PASSWORD =
XYZXYZ.

SendError

Indicates if a message of type error is YES - a message of type error is sent to the user exit. sent to the user exit. NO - a message of type error is not sent to the user exit.

30-20

Handling Errors Branching to Another Form for a Field Value

Entry Name SendWarning

Explanation Indicates if a message of type warning is sent to the user exit.

Valid Values YES - a message of type warning is sent to the user exit. NO - a message of type warning is not sent to the user exit. YES - a message of type information is sent to the user exit. NO - a message of type information is not sent to the user exit.

SendInformation Indicates if a message of type information is sent to the user exit.

The following is sample C code for a user exit:

#include "sapemsg.h" void SAPEMSG(stExitRoutine *pExitRoutine,stExitCalling *pExitCalling,stExitMessage *pExitMessage) { printf("SAPEMSG - Start program.\n"); switch ( pExitRoutine->iAction ) { case( EXIT_ROUTINE_ACTION_START ) : printf("SAPEMSG - Action start.\n"); break; case( EXIT_ROUTINE_ACTION_PROCESS ) : printf("SAPEMSG Action process.\n"); printf("SAPEMSG pExitMessage->iClass : %d.\n",pExitMessage>iClass); printf("SAPEMSG pExitMessage->iSubClass : %d.\n",pExitMessage>iSubClass); printf("SAPEMSG pExitMessage->iSeverity : %d.\n",pExitMessage>iSeverity); printf("SAPEMSG pExitMessage->iSystem : %d.\n",pExitMessage>iSystem); printf("SAPEMSG pExitMessage->iCode : %d.\n",pExitMessage>iCode); printf("SAPEMSG pExitMessage->iType : %d.\n",pExitMessage>iType); printf("SAPEMSG pExitMessage->pcTextLine : %s.\n",pExitMessage>pcTextLine); printf("SAPEMSG pExitMessage->pcFileName : %s.\n",pExitMessage>pcFileName); printf("SAPEMSG pExitMessage->iLineNumber : %d.\n",pExitMessage->iLineNumber);
30-21

30

Handling Errors Branching to Another Form for a Field Value

} printf("SAPEMSG - End program.\n"); return;

:

break; case( EXIT_ROUTINE_ACTION_END ) : printf("SAPEMSG - Action End.\n"); break;

#ifndef SAPEMSG_H #define SAPEMSG_H #include "sapexit.h" #include "sapexitm.h" void SAPEMSG(stExitRoutine *pExitRoutine,stExitCalling *pExitCalling,stExitMessage *pExitMessage); #endif /* SAPEMSG_H */ #ifndef SAPEXIT_H #define SAPEXIT_H #define MAX_TEXT_RC 80+1 typedef struct { int int char void int char } stExitRoutine; typedef struct { int int char unsigned int unsigned int unsigned int } stExitCalling;

iType; iAction; *pcParmStr; *pvWorkArea; iRC; cTextRC[MAX_TEXT_RC];

iType; iSubType; *pcName; iNumber; iProcessNum; iThreadNum;

30-22

Handling Errors Branching to Another Form for a Field Value

/*****************************************************/ /* stExitRoutine.iType */ /*****************************************************/ #define EXIT_ROUTINE_TYPE_MESSGAE 1 /*****************************************************/ /* stExitRoutine.iAction */ /*****************************************************/ #define EXIT_ROUTINE_ACTION_START 1 #define EXIT_ROUTINE_ACTION_PROCESS 2 #define EXIT_ROUTINE_ACTION_END 3 #endif /* SAPEXIT_H */ #ifndef SAPEXITM_H #define SAPEXITM_H typedef struct { int iClass; int iSubClass; int iSeverity; int iSystem; int iCode; int iType; char *pcTextLine; char *pcFileName; int iLineNumber; } stExitMessage; /*****************************************************/ /* stExitMessage.iSystem */ /*****************************************************/ #define EXIT_MESSAGE_SYSTEM_TAM 1 #define EXIT_MESSAGE_SYSTEM_SAP 2 #define EXIT_MESSAGE_SYSTEM_SYS 3 /*****************************************************/ /* stExitMessage.iType */ /*****************************************************/ #define EXIT_MESSAGE_TYPE_INF 1 #define EXIT_MESSAGE_TYPE_ERR 2 #define EXIT_MESSAGE_TYPE_WRN 3 #define EXIT_MESSAGE_TYPE_TRC 4
30-23

30

Handling Errors Branching to Another Form for a Field Value

/*****************************************************/ /* stExitMessage.iSeverity */ /*****************************************************/ #define EXIT_MESSAGE_SEVERITY_NOT_RELEVENT -1 /*****************************************************/ /* if stExitMessage.iType == EXIT_MESSAGE_TYPE_INF */ /*****************************************************/ #define EXIT_MESSAGE_SEVERITY_SUCCESS 0 #define EXIT_MESSAGE_SEVERITY_MESSAGE 2 /*****************************************************/ /* if stExitMessage.iType == EXIT_MESSAGE_TYPE_WRN */ /*****************************************************/ #define EXIT_MESSAGE_SEVERITY_WARNING 4 /*****************************************************/ /* if stExitMessage.iType == EXIT_MESSAGE_TYPE_ERR */ /*****************************************************/ #define EXIT_MESSAGE_SEVERITY_GROUP_FAILURE 6 #define EXIT_MESSAGE_SEVERITY_GROUP_RETRY 7 #define EXIT_MESSAGE_SEVERITY_ERROR 8 #define EXIT_MESSAGE_SEVERITY_TERMINATE_USER 12 #define EXIT_MESSAGE_SEVERITY_ENV_FATAL 16 #define EXIT_MESSAGE_SEVERITY_ENV_FATAL_ERROR 20 /*****************************************************/ /* stExitMessage.iClass */ /*****************************************************/ #define EXIT_MESSAGE_CALLS_COMMUNICATION 1 #define EXIT_MESSAGE_CALLS_PARSING 2 #define EXIT_MESSAGE_CALLS_TUNING 3 #define EXIT_MESSAGE_CALLS_DATASOURCE 4 #define EXIT_MESSAGE_CALLS_APPLICATION LOGIC 5 #define EXIT_MESSAGE_CALLS_INFRASTRUCTURE 6 #define EXIT_MESSAGE_CALLS_AUTHENTICATION 7 #define EXIT_MESSAGE_CALLS_DEVELOPMENT LOGIC 8 #define EXIT_MESSAGE_CALLS_AUTHORIZATION 9 #endif /* SAPEXITM_H */

30-24

Chapter 31 Rule Analyzer

Rules are an essential part of any concept model. A typical concept model can contain many rule models. Each rule model can itself contain many rulesets and each ruleset in turn can contain many ruleseach rule referencing many fields. Moreover, field values can be moved between fields in different rules via derivation and fetch rules, rules can call other rules, and rule triggering can be a recursive process. As the complexity of the concept model increases, so does the difficulty of keeping track of rule behavior. For example:

Impacts can occur on the same field from different rules. Conflicts can arise between different rules assigning values to the same field. Sequencing problems can exist where a field is referenced by a rule before the field is assigned a value.

To help analyze and resolve impact, conflict, and sequencing problems within a rule model, Rule Analyzer provides three types of analysis: impact analysis, conflict analysis and sequencing analysis. The following considerations apply to Rule Analyzer:

Only rules triggered by a class are analyzed by Rule Analyzer. Parameter fields used in programs called via a call rule are not currently in the scope of analysis performed by Rule Analyzer. Rules that are part of a dynamic ruleset are not analyzed by Rule Analyzer.

31-1

31

Rule Analyzer Impact Analysis

31.1 Impact Analysis

Impact analysis is performed on field objects in a rule model. It involves listing all the rules that reference a particular field of a particular rule of a particular ruleset.

Example: The figure depicts a situation showing several classes that trigger rulesets. Field values are derived to, and fetched from, the classes via rules. An impact analysis is performed for Field2 of Rule 5 of Ruleset 2 of Class 2. The result of the impact analysis is a list (not shown here) containing all the rules that reference Field2. The list is arranged in the order in which the rules reference Field2. Rules that reference Field2 before Field2 is referenced by Rule 5 (the current rule), are listed firstwith an arrow indicating that they impact Field2 earlier in the rule triggering sequence. Rules that reference Field2 after Field2 is referenced by Rule 5 (the current rule), are listed afterwardswith an arrow indicating that they impact Field2 after the current rule in the rule triggering sequence. By inspecting the impact results, you can obtain a comprehensive understanding of how a particular field is used in the rule model.

31-2

Rule Analyzer Conflict Analysis

31.2 Conflict Analysis

Conflict analysis is performed on field objects in a rule model. It involves listing all the rules assigning (setting) a value for a particular field in the rule model.

Example: The figure depicts a situation showing several rulesets triggered by Class 2. Field33 is assigned a value in Rule 5 of Ruleset 2. Field33 is assigned a different value in Rule 8 of Ruleset 3. The situation depicted presents a potential conflict in assigning values to Field33. By inspecting the conflict results, you obtain a comprehensive understanding of how a particular field obtains values in a rule model. You can then decide if the field value assignments are in conflict.

31-3

31

Rule Analyzer Sequencing Analysis

31.3 Sequencing Analysis

Sequencing analysis is performed on field objects in a rule model. It involves listing all the rules assigning (setting) values to a particular field in a rule model in an order that appears to be incorrect.

Example: The figure depicts a situation showing several rulesets triggered by Class 2. The value of Field33 is used in a conditional test in Rule 5 of Ruleset 2. However, Field33 is first assigned a value in Rule 8 of Ruleset 3. Since Rule 8 is triggered after Rule 5, a sequencing problem in the usage of Field33 within the rule model exists. By inspecting the sequencing results, you obtain a list of actual and potential sequencing problems in the usage of field values in the rule model.

31.4 Rule Analyzer via Development Workbench

Rule Analyzer is an integral part of Development Workbench. You can invoke an impact, conflict or sequencing analysis by expanding the Impact Analysis, Conflict Analysis or Sequencing Analysis nodes displayed in the navigation pane of Development Workbench. Rule Analyzer lists the objects found in the analysis under the expanded node in the tree of the navigation pane.

31-4

Rule Analyzer Rule Analyzer via Development Workbench

Objects listed in the navigation pane by Rule Analyzer are colored blue to distinguish them as objects displayed as a result of an analysis.

Symbols Displayed in the Navigation Pane

The following symbols are displayed in the navigation pane when using Rule Analyzer. A selected symbol is displayed on a yellow background. Symbol Meaning current class being analyzed (level 0) class at lower level than the analyzed class class at higher level than the analyzed class trigger (a ruleset)

31-5

31

Rule Analyzer Rule Analyzer via Development Workbench

Symbol triggered rule

Meaning

displayed alongside a rule symbol to indicate that a field value is set in the rule field referenced in a rule that is not in the current class (e.g. a global field, a field fetched from another class, a field derived to the current class) field referenced in a rule that is in the current class impact analysis conflict analysis sequencing analysis rule (listed in analysis results) that is triggered before analyzed rule rule (listed in analysis results) that is triggered after analyzed rule

Triggering Objects
Rule Analyzer performs an analysis for fields in rules that are triggered by a particular triggering object (e.g. a composite or a class).

31-6

Rule Analyzer Rule Analyzer via Development Workbench

For each ruleset triggered by a triggering object, you can obtain a detailed analysis listing impacts, conflicts or potential sequencing problems for any field in any rule in any ruleset triggered by any class.
composite
(triggering object)

analyzed class

Impact Analysis
for Field 1904 of rule #1 of ruleset #10

(trigger)

analyzed ruleset analyzed rule classes impacting Field 1904 rules impacting Field 1904 of analyzed rule #1 from impacted Class 20

The following is some of the information displayed for each of the rules (triggered via a class) impacting on an analyzed field:
ruleset number rule number rule name rules triggered before analyzed rule rule setting a value for the analyzed field

When expanding a rule that impacts on an analyzed field, the fields referenced in the rule that impact on the analyzed field are listed:

fields impacting analyzed Field 1904 of analyzed rule #1 from rule #20 of ruleset #211340 triggered by Class 20

31-7

31

Rule Analyzer Performing an Impact Analysis

31.5 Performing an Impact Analysis

In order to perform an impact analysis, you must understand the role of class levels. After performing the analysis, you can investigate various types of impact:

How the field is used in a particular rule triggered by a particular class. The impact details for a particular impacting class. How the analyzed field is used in a particular rule under a particular impacting class.

You can continue investigating further branches of the tree.

Class Levels
The rule triggering sequence order in a rule model is not the only process that governs the order by which field values in a rule model are affected. Propagation (via derivation rules) and branching (via THEN/ELSE clauses) also affect field impact order. The power of Rule Analyzer is its ability to analyze and make available information on propagated impacts that result from derivations between classes as well as impacts due to branching between rules. In a propagated impact, a field in the analyzed class (level 0) can receive its value from a field in a lower level class (level -1, -2, etc.) via a MOVE keyword in a rule statement. The field in the analyzed class may or may not have the same name as the field from which its value is derived. Then/Else branching also affects the propagation.
level -1 level 0 level 1

class 1
Move

class 2
field2 field3
Move

class 3
field2 field4

field1

An analyzed field is the field under investigation. It can be impacted directly or indirectly by other fields. Via rules, its value can be set by other fields in the same class or from other classes, or it can set values of other fields in the same class or in other classes. In addition, its value is sometimes only used in rules and is not set by other fields. For an analyzed field, an impact analysis finds all direct or indirect impacts on, or from, the analyzed field that use or set the value of the analyzed field.
31-8

Rule Analyzer Performing an Impact Analysis

For illustration purposes, the impact diagram shown below details some of the classes and some of the derivations between fields in the classes, as well as the class levels with respect to the field of the impact study (Field 1904) for a particular concept model. The only fields listed in the diagram are fields involved in derivations (they are either derived to, or derive from, another field in the same class or across different classes) with respect to Field 1904. In Class 19 (the analyzed class, level 0), Field 1904 sets values for the other fields listed in Class 19. The emphasized section of the impact diagram is used in the discussed impact examples. When analyzing a field via an impact analysis, more attention should be paid to the field numbers (which are unique in eMerge for a given field) and less to the field name (since field names can have synonyms and may be used in a rule via their synonym name).
Impact Diagram for Field 1904 composite 19, class 19
(derived )

class level 1
Comp 2 Class 2 Field 1901

section of diagram used in impact example

class level -2
comp 467 class 449 field 1901

analyzed class

Comp 4 Class 4 Field 1901

class level -1
comp 4 class 2023 field 1901

class level 0
comp 19 class 19 fields:

Comp 109 Class 190 Field 10906

comp 467 class 444 field 1901 comp 4 class 2024 field 1901

class level 2
comp 109 Class 1090 Field 10907 comp 109 class 1092 fields: 10907 10908 comp 4 class 2024 field 1901

1904
1956 1901 1971 1925 1926

comp 467 class 444 field 1901

comp 467 class 449 field 1901

comp 4 class 2023 field 1901

31-9

31

Rule Analyzer Performing an Impact Analysis

The impact analysis described below is for an analyzed field (Field 1904), impacted by fields from other classes, that do not, in the propagation process, set a value for the analyzed field. Example: An impact analysis on the Parent Cns (1904) field is performed. The field is referenced in the Compute Composite No (10) rule of the Call For 19 (1915) ruleset triggered by the Constructor class. Parent Cns is a field used in the Constructor class:
composite triggering class trigger (ruleset)

triggered computation rule

Impact Analysis on the Field Level

To perform an impact analysis on the field level:

1 Expand the relevant composite, class, trigger and rule in the navigation pane of Development Workbench (e.g. as shown in the above figure):

Expand the composite that contains the triggering class for the ruleset that has the rule that references the field on which you want to perform the impact analysis. (e.g. Constructor). Expand the class that is the triggering class for the ruleset containing the rule that references the field on which you want to perform the impact analysis (e.g. Constructor). Expand the trigger (e.g. the Call For 19 ruleset) for the rule that contains the field (e.g. Field 1904). Expand the rule (e.g. the Compute Composite No rule) containing the field.

31-10

Rule Analyzer Performing an Impact Analysis

2 Expand the Impact Analysis node listed under the field:

Impact analysis for Field 1904

impacting classes

class level class number class name

Rule Analyzer lists the classes that contain fields that are impacted by, or that impact on, Field 1904. For each class, the class level (with respect to Class 19, which is level 0) the class number and class name are listed. Classes at a level lower than Class 19 are indicated with a red up-arrow. Classes at a level higher than Class 19 are listed with a red down-arrow.

Use of a Field in a Rule Triggered by a Class

You can investigate how the field is used in a particular rule triggered by a particular class.

31-11

31

Rule Analyzer Performing an Impact Analysis

To investigate how the field is used in a rule triggered by a class: Expand the impacting class of interest. For example, expand the Edit Trigger (2024) class:
Impact Analysis for the Parent Cns field

rules triggered from Class 2024

The rules listed under the Edit Trigger (2024) class are the rules that impact on the value of field Parent Cns in the rule model. Rules listed with a red exclamation point alongside their rule symbol are rules that set values for Field 1904. Rules listed without a red exclamation point are rules that only use the value of Field 1904. In the current example (no red exclamation point displayed) the rules listed for the Edit Trigger class use the value of the field being analyzed but do not set a value for the field being analyzed. Rules listed with a red up-arrow are triggered before the analyzed rule (Rule Compute Composite No), and rules listed with a red down-arrow are triggered after the analyzed rule.

Impact Details for an Impacting Class

You can view the impact details for a particular impacting class.

To view the impact details for a particular impacting class:

1 Right-click the class name in the tree.

31-12

Rule Analyzer Performing an Impact Analysis

2 Choose Class Impact Details from the pop-up menu that is displayed. The Class Impact Details (10467) form is displayed:

For example, to view the impact details for the Edit Trigger class, rightclick the class name in the tree, and choose Class Impact Details from the pop-up menu that is displayed.

Use of a Field in a Rule Under an Impacting Class

You can investigate how the analyzed field is used in a particular rule under a particular impacting class.

To investigate how the field is used in a rule under an impacting class:

1 Expand a rule listed under an impacting class. The fields referenced in the rule are listed. For example, to investigate how the Parent Cons field is used in the Update Counter In Index Cns rule under the Edit Trigger class, expand the Update Counter In Index Cns (10) rule of Ruleset 22449, under the Edit Trigger class.

31-13

31

Rule Analyzer Performing an Impact Analysis

2 Right-click a rule listed under an impacting class. Choose Open from the pop-up menu that is displayed. The rule definition form for the rule is displayed. For example, right-click the Update Counter In Index Cns (10) rule of Ruleset 22449. Choose Open from the pop-up menu.

With the tree in the navigation pane and the rule definition form displayed for the rule selected from the analysis list, you can investigate the propagation behavior. 3 Examine the symbols for the rule in the navigation pane. See "Symbols Displayed in the Navigation Pane" on page 5. From the symbol for the Update Counter In Index Cns rule, you can learn this information:

The rule is triggered before the current rule (red up-arrow). The rule contains a statement that does not set the value of a field that impacts on the field under investigation (no red exclamation point).

4 Examine the rule.

31-14

Rule Analyzer Performing an Impact Analysis

CONSTRUCTOR-NO IS PATH

is the statement using Field 1904 in the rule.

5 Right-click the rule again and choose Rule Impact Details from the pop-up menu that is displayed. The Rule Impact Details form is displayed: For example, right-click the Update Counter In Index Cns rule and choose Rule Impact Details from the pop-up menu.

The Rule Impact form lists information on the analyzed rule and the impacted rule: Analyzed Rule The Analyses Rule sub-groupbox contains this information:

The name and number of the analyzed rule (e.g. Compute Composite No), its composite, class and ruleset. The name and number of the analyzed field (e.g. Parent Cns, Field 1904) in the analyzed rule.

31-15

31

Rule Analyzer Performing an Impact Analysis

Impacted Rule

The Impacted Rule sub-groupbox contains this information:

The name and number of the impacted rule (e.g. Update Counter In Index Cns), its composite, class and ruleset. The name and number of the impacting field (listed in the Field textbox, e.g. Field 1901) from the impacted rule that impacts directly or indirectly on the field being analyzed (that impacts on Field 1904). The name and number of the impacted field, listed in the Impacted from Field textbox from the analyzed class, that is being directly impacted on by the field listed in the Field textbox. In the example above, Field 1901 from the Class 2024 (at level -1 with respect to the analyzed class) referenced in ruleset #22429, rule #10, impacts directly on Field 1901 in the analyzed rule. Not shown on the form (but shown on the impact diagram above) is the fact that Field 1901 in the analyzed class is impacted on from Field 1904 in the same class. Thus Field 1901 in Class 2024 is indirectly impacting on Field 1904 in class 19.

Investigating further Branches of the Tree

Expand the rule node. A list of all the fields referenced by the rule are displayed under the rule node:

You can now proceed to investigate these fields or other rules referencing the analyzed field.

Impact Analysis on the Class Level

Sometimes a problematic field on which impact information is required is not listed in the navigation pane under a rule when performing an impact analysis on the field level. This situation occurs when the field is not referenced directly in the rule but is involved in a derivation. In such a case, impact analysis on the field is performed via the class level (since a field is always listed under a class in the navigation pane).

31-16

Rule Analyzer Performing an Impact Analysis

To perform an impact analysis on the class level:

1 In the navigation pane, expand the class that contains the field on which you want to perform impact analysis. 2 Expand the Impact Analysis node:

triggering class

field in class

Impact Analysis for field in class

The list of fields displayed under the class is a list of all the fields defined for the classeven though the fields are not referenced in a rule. This is different than the field list displayed when performing Impact Analysis on the field level. The field list displayed when performing Impact analysis on the field level only list fields that are referenced or used in a rule.

3 Expand the field under Impact Analysis which you want to analyze:

31-17

31

Rule Analyzer Performing a Conflict Analysis

4 Proceed to perform the impact analysis on the field as indicated in "Impact Analysis on the Field Level" on page 10.

If the field is not referenced or used by any rule, then when the field is expanded under Impact Analysis, an empty list is displayed.

31.6 Performing a Conflict Analysis

When the value of a field is set more than once via a rule in a rule model, a potential conflict can exist for the value of the field. For example, setting the value for a field, using the set field value, then resetting the value for the field and using the reset value, are usages for a field value that do not necessarily conflict. However, setting a value for a field, resetting the field value and then using the field value, is a potential conflict in the usage of the field value. To help resolve such situations, Rule Analyzer performs a conflict analysis for a field, the results of which indicate rules that set the value of a field.
31-18

Rule Analyzer Performing a Conflict Analysis

Rule Analyzer filters the analysis results and does not display rules that set a value for the analyzed field but cannot be in conflictdue to triggering on different conditions. Therefore, not all the rules listed for an impact analysis that set a value for the analyzed field, are necessarily listed in the conflict analysis results. For example, a rule that sets an analyzed field value but is triggered only OnDelete does not conflict with rules setting a value for the analyzed field that are triggered only OnInsert or OnChange. Also rules in nested THEN/ELSE rulesets do not conflict, since either the THEN or the ELSE condition is triggered. By inspection of the results you can decide if the usage is in conflict. Conflict analysis can be performed on the field or class level.

Conflict Analysis on the Field Level

Example: A conflict analysis is performed on temporary field Temp Parent Cns (Field 114) of the Compute Composite No (10) rule:

To perform a conflict analysis on the field level:

1 In the navigation pane of Development Workbench, expand the class that is the triggering class for the ruleset containing the rules (that references the field) on which you want to perform the conflict analysis. Expand the trigger (e.g. ruleset Call For 19) for the rule that contains the field. Expand the rule (e.g. rule Compute Composite No) containing the field. Expand the Conflict Analysis node listed under the rule:

31-19

31

Rule Analyzer Performing a Conflict Analysis

2 Expand the field on which you want to perform the conflict analysis (e.g. expand Temp Parent Cns, Field 114):

Conflict Analysis
for Field 114

Rule Analyzer lists the rules in the rule model that set values for Field 114 (rules with red exclamation point). Investigate the rule statements for any of the rules listed (by rightclicking the rule and choosing Open from the pop-up menu that is displayed) to decide if the potential conflict is a real conflict.

Conflict Analysis on the Class Level

Example: A conflict analysis is performed on the Constructor (19) class of composite Constructor (Class 19).

To perform a conflict analysis on the class level:

1 In the navigation pane of Development Workbench, expand the class on which you want to perform the conflict analysis:

31-20

Rule Analyzer Performing a Conflict Analysis

analyzed class

conflict analysis
on class level

2 Expand Conflict Analysis (listed immediately after the class triggers). The fields referenced by the class are listed:

31-21

31

Rule Analyzer Performing a Sequencing Analysis

3 Expand a field (e.g. the Temp Parent Cns (114) field). The rules setting a value for the field are listed:

Investigate the rule statements for any of the rules listed (by rightclicking the rule and choosing Open from the pop-up menu that is displayed) to decide if the potential conflict is a real conflict.

31.7 Performing a Sequencing Analysis

When the value of a field is used in one rule statement and then set in another rule statement (that is triggered after the rule that uses the field value), a potential sequencing problem exits for the usage of the field value in the rule model. To help resolve such situations, Rule Analyzer performs a sequencing analysis for an analyzed field in an analyzed rule, listing the following:

When the value for the analyzed field is set in the analyzed rule, Rule Analyzer lists all rules that are triggered prior to the analyzed rule that use the value for the analyzed field. When the value for the analyzed field is used in the analyzed rule, Rule Analyzer lists all rules that are triggered after the rule that set the value for the analyzed field.

Rule Analyzer filters the analysis results and does not display rules for the analyzed field that cannot have sequencing problemsdue to

31-22

Rule Analyzer Performing a Sequencing Analysis

triggering on different conditions. Therefore, not all the rules listed for an impact analysis that set a value for the analyzed field, are necessarily listed in the sequencing analysis results. For example, a rule that sets an analyzed field value but is triggered only OnDelete does not have a sequencing problem with rules setting a value for the analyzed field that are triggered only OnInsert or OnChange. Also rules in nested THEN/ELSE rulesets do not have a sequencing problem, since either the THEN or the ELSE condition is triggered. sequencing analysis can be performed on the field or class level.

Sequencing Analysis on the Field Level

Example: A sequencing analysis is being performed on temporary field Temp Parent Cns (Field 114) of rule Compute Composite No (rule #10):

To perform a sequencing analysis on the field level:

1 In the navigation pane of Development Workbench, expand a class (e.g. class Constructor, Class 19) that is the triggering class for the rulesets on which you want to perform the sequencing analysis. Expand a trigger (e.g. ruleset Call For 19) for the class. Expand a triggered rule whose fields you want to sequence analyze (e.g. rule Compute Composite No, rule # 10):

2 Expand Sequencing Analysis. The fields referenced in the rule are listed. 3 Expand a field in the rule (e.g. Field 114). The following sequencing analysis results are listed for Field 114: The value for the analyzed field (Field 114) is used (not set) in rule Dividsor For 3000 to 9999 (rule #20 in ruleset #1988). The sequencing
31-23

31

Rule Analyzer Performing a Sequencing Analysis

analysis for that rule lists rules: Compute Composite No, Get Conect Field From Parent, Fetch Parent Cns in Link 1, and Initiation. Each of the listed rules are rules that are triggered after rule Dividsor For 3000 to 9999 and each sets a value for the analyzed field. The value for the analyzed field is set in rule Compute Composite No (rule #10 of ruleset #1915). Expanding rule Compute Composite No, lists rules: Dividsor For 3000 to 9999 (rule #20 in ruleset #1988) and rule Dividsor For 1130 to 2999 (rule #25 in ruleset #1988). Each of the listed rules are rules that are triggered before rule Compute Composite No and that only use the value of the analyzed field.

Sequencing Analysis on the Class Level

Example: A sequencing analysis is being performed on class Constructor (Class 19) of composite Constructor (Class 19).

To perform a sequencing analysis on the class level:

1 In the navigation pane of Development Workbench, expand the class on which you want to perform the sequencing analysis:
analyzed class

sequencing analys
on class level

31-24

Rule Analyzer Performing a Sequencing Analysis

2 Expand Sequencing Analysis (listed immediately after the class triggers). The fields referenced by the class are listed:

3 Expand a field (e.g. Temp Parent Cns, Field 114). The following sequencing analysis results are listed for Field 114:

The value for the analyzed field (Field 114) is used (not set) in rule Dividsor For 3000 to 9999 (rule #20 in ruleset #1988). The sequencing
31-25

31

Rule Analyzer Rule Analyzer in Batch

analysis for that rule lists rules: Compute Composite No, Get Conect Field From Parent, Fetch Parent Cns in Link 1, and Initiation. Each of the listed rules are rules that are triggered after rule Dividsor For 3000 to 9999 and each sets a value for the analyzed field. The value for the analyzed field is set in rule Compute Composite No (rule #10 of ruleset #1915). Expanding rule Compute Composite No, lists rules: Dividsor For 3000 to 9999 (rule #20 in ruleset #1988) and rule Dividsor For 1130 to 2999 (rule #25 in ruleset #1988). Each of the listed rules are rules that are triggered before rule Compute Composite No and that only use the value of the analyzed field.

31.8 Rule Analyzer in Batch

Rule analysis can be performed in a batch session instead of "online" via Development Workbench. The same analyses are available in batch as in an online session. From a batch session, you run a utility program via the PERFORM statement, passing the parameters that define the analysis to be performed. The results of the analysis are placed in a class structure in memory. To retrieve the results of the analysis, prepare a query or program to read and process the results. If the analysis discovers a sequence problem between rulesets or rules, you can re-run the analysis specifying an alternate order for invoking the rulesets or rules. This way, you can determine whether the conflict can be eliminated by reordering rulesets, or rules within a ruleset.

31.9 SAPANLYS Program

Input Parameters
The SAPANLYS (1430) program accepts the following input parameters to define the analysis to be performed: No. Field name 1 2 3
31-26

Field Field Valid Must type length values binary 4 binary 4 binary 2 Y N N

Description class to search ruleset to check rule to check

object ruleset rule

Rule Analyzer SAPANLYS Program

No. Field name 4 5 6 7 8 9 field object2 max-level mode object-type query

Field Field Valid Must type length values binary 2 binary 2 binary 2 char char 1 1 I/C/ S/A C N Y N Y Y N N N N N

Description field to check composite to search maximum derivations impact / conflict / sequencing / all class query number to run program no. to run (internal use) alt. ruleset position alternate rule position

binary 4 binary 4 char 1 binary 4 binary 2

10 program 11 ind 12 ruleset opt pos 13 rule opt pos Object Ruleset Rule Field Object2 Max-level

The number of the class on which the analysis is to be performed. The ruleset to be checked. (Impact Analysis only.) The rule to be checked. (Impact Analysis only.) The field to be checked. (Impact Analysis only.) The number of the composite containing the class on which the analysis is to be performed. The maximum derivation level to search. (Impact Analysis only.) 0 1 2 All levels (default) only the current level the current level and the next one, etc.

Mode

The type of analysis to perform: I C S A Impact Conflict Sequencing Conflict and Sequencing mode.
31-27

31

Rule Analyzer SAPANLYS Program

Object-type

The triggering object is a class. C Class

Query

The number of a user-written query to be run after the utility finishes, to extract the results of the analysis from memory. See "Sample Query to Print Results" on page 31-32. The number of a user-written program to be run after the utility finishes, to extract the results of the analysis from memory. For internal use. An alternate position for the ruleset, for this run. (Sequence analysis only.) See "Testing Alternate Positioning for Rulesets and Rules" on page 31-32. An alternate position for the rule, for this run. (Sequence analysis only.) See "Testing Alternate Positioning for Rulesets and Rules" on page 31-32.

Program Ind Ruleset opt pos

Rule opt pos

Running the SAPANLYS Program

Syntax Run the SAPANLYS program by issuing the PERFORM command for program number 1430, followed by the parameters separated by commas:
PERFORM 1430,<class>,<ruleset>,<rule>,<field>,<composite>, <max-level>,<mode>,C,<query>,<program>,,<ruleset-opt-pos>, <rule-opt-pos>

To skip parameters, enter a comma as placeholder. Batch Rule Analysis Example The tree below shows the result of an online impact analysis on the Parent Cns (1904) field. The field is referenced in the Compute Composite

31-28

Rule Analyzer SAPANLYS Program

No (10) rule of the Call For 19 (1915) ruleset triggered by the Constructor class. Parent Cns is a field used in the Constructor class:
triggering class trigger (ruleset)

triggered computation rule

To perform the Impact analysis shown above, in batch, for triggering class 19, Ruleset 1915, Rule 10, Field 1904, the command would be as follows:
PERFORM 1430,19,1915,10,1904,19,,I,C,<query>

Output Format
After the utility is run, the results are stored in memory, in the Rule Analysis (10470) composite. You can retrieve the results by writing a rule or a program to do so. See "Sample Query to Print Results" on page 31-32. Rule Analysis Class The Rule Analysis (10470) class contains sequence numbers and the input parameters for the rule analysis utility.

31-29

31

Rule Analyzer SAPANLYS Program

COMPOSITE: | SEQ.

RULE ANALYSIS (10470) | SEQ. NEXT| OBJECT | FREE | (10574) | B/4 | NO | (23383) | B/4

CLASS:

RULE ANALYSIS (10470) | RULE NO. | FIELD | 700) B/4 | (20023) | B/2 | NO. | ( | 110) B/2 | | | |

************------------------------------------------------------| RULESET | NO. | ( | | COUNTER | (10588) | B/4

************-----------------------------------------------------------------------------------------------------------------------| CONCEPT | CMP | (10394) | B/2 | ANALYSIS | OBJECT | | MODE C/1 | TYPE | (10514) | C/1 | (10513) | RULESET | (10517) | B/4 | RULE OPT | ONE RULE | POS. B/2 | | PER CLS | | | C/1 | (10518) | | (10511) | OPT POS. |

-------------------------------------------------------------------------------------------------| PATH | LEVEL | (11097) | B/2 | REQ | OBJECT1 | (10547) | B/4 | REQ | OBJECT2 | (10548) | B/2 | | | |

---------------------------------

SEQ. COUNTER If there are more than the maximum number of occurrences of the Analysis Result (10471) class under this root class, additional occurrences of the root class are created. This field is the sequence number of the occurrence of the root class. SEQ. NEXT FREE This field points to the next root occurrence in the chain. If there are no additional occurrences of the root class, this field contains a zero. Analysis Result Class The Analysis Result (10471) class contains the analysis result.

31-30

Rule Analyzer SAPANLYS Program

COMPOSITE:

RULE ANALYSIS (10470) | FIELD | NO. | ( | 110) B/2 B/2

CLASS:

ANALYSIS RESULT (10471) | CONCEPT | CMP | (10394) | B/2 B/4 | | | |

************------------------------------------------------------| SEQ NO | | ( 1585) | | RULESET | NO. | ( | 700) B/4 | RULE NO. | OBJECT | | (20023) | B/2 | NO | (23383) |

************-----------------------------------------------------------------------------------------------------------------------| LEVEL NO | IMPACT | | (10477) | B/2 | (10510) | B/2 | CHECKSET | ACCESS | | (21011) | Z/1 H/2 | (10512) | | RULESET | ACCESS | (10516) | Z/1 | OBJECT1 | ACCESS | (10519) | Z/1 | | | | | FROM FLD |

--------------------------------------------------------------------------------------| OBJECT2 | ACCESS | (10549) | Z/1 | INF FLD | ACCESS | (10509) | Z/1 | | | |

-------------------

SEQ-NO

sequence number

FIELD-NO The number of the field that has an impact conflict or a sequencing problem with the input rule. RULESET-NO/RULE-NO The numbers of the ruleset and rule that has impact, sequence or conflict problem with the input rule. OBJECT-NO/CONCEPT-CMP The numbers of the class and the composite that has impact, sequence or conflict problem with the input rule because of derived rules. (Relevant for impact analysis only.) LEVEL-NO The class and the composite derivation level. The level is negative for derived from, zero for current class and positive for derivation to. (Relevant for impact analysis only.) IMPACT-FROM-FLD at derivation rule the utility propagate fields (move A to B), that field describe who propagate the field, zero mean that the field invoke from the input parameters (relevant for impact analysis only), CHECKSET 8000 4000 Indicates one or more of the following options:

rule before input rule rule after input rule

31-31

31

Rule Analyzer SAPANLYS Program

2000 1000 0800 0400

the field get value conflict problem sequence problem field is not temp field

ACCESS/RULESET ACCESS/OBJECT1 ACCESS/OBJECT2 ACCESS/INF FLD ACCESS Security access for the field / ruleset / class / composite / infected field. 0 forbidden retrieve or update

<non-zero>

Sample Query to Print Results

The output of the analysis is placed in temporary class (10470). In order to read the output, you must supply to the analysis utility the number of a query or a program that will read the output class (10470) and print or process it. Create a query such as the following to read and print the results of the analysis.
for all analysis-result. print field-no ruleset-no rule-no object-no concept-cmp level-no impact-from-fld.

Testing Alternate Positioning for Rulesets and Rules

If a sequence analysis discovers conflicts between rulesets or rules, you can re-run the analysis specifying an alternate order for invoking the rulesets or rules. This way you can determine whether the conflict can be eliminated by reordering rulesets or rules within a ruleset. Alternate Positioning for a Ruleset Alternate Positioning for a Rule Specify the alternate position of the ruleset being checked, in the Ruleset opt pos parameter. Specify the alternate position of the rule being checked, in the Rule opt pos parameter. There cannot be an existing rule with this number in the ruleset.

31-32

Part D

Accessing the Data

Chapter 32 Accessing the Data

Messages are used to transfer information between the Workspace Layer and the Enterprise Layer. To access the data within an application (i.e. to retrieve or update the data), messages are sent to the Business Logic Processor (BLP). The BLP retrieves or updates the appropriate data occurrences based on the message. In eMerge, there are the following types of message:

operation parameter transfer (via a query or program)

Operations can update the data or produce listings or forms (see Chapter 33, Operations and Operation Methods for details). A query or a program can generate its own operation which then functions like any operation. A query can produce a listing (See Part G Reports and Queries for details). A program can update the data without generating an operation (See Part H External Programs for details).

32-1

32

Accessing the Data

Note that any update or retrieval via an operation triggers any rules attached to the data.

32-2

Chapter 33 Operations and Operation Methods

Within eMerge the enterprise layer is accessed via messages sent to and from the workspace layer. Business Logic Processor (BLP) retrieves or updates the appropriate data occurrences based on the message. In eMerge, there are the following types of messages:

operation parameter transfer (done via a query or a program)

Operations can update the data or produce listings or forms. Business components are based on operations. A query or a program can generate its own operation which then functions like any operation. An operation can contain: an operation code (e.g. Insert, Edit, Delete) input fields output fields a target concept operation methods An operation can trigger rulesets: issue rulesets edit rulesets Stored in the knowledgebase, an operation is an input structure with an operation code and destination target concept. The operation accesses the fields in the target concept for viewing or for update. Included in the operation definition are the fields upon which the operation is performed. The developer can define any operations needed for retrieval or update by including as many fields as needed. When the operation reaches the Business Logic Processor, the Business Logic Processor checks the operation and the fields in the operation for errors and then retrieves/updates the appropriate data. The data is identified by the key field of the target concept together with the keys of all parent concepts.

33-1

33

Operations and Operation Methods Invoking Operations

The following steps are performed when the Business Logic Processor processes an operation: 1 Validate the data. Field values are checked to ensure that the input matches the field data type. Subject checking is also done. 2 Execute issue rules. Any rules attached to the operation or block are executed. 3 Access the data. The data is accessed and the relevant occurrence is checked. For listing, change, and delete operations, the occurrence must exist. For insert operations, the occurrence must not exist. 4 Update the data if required. 5 Execute any relevant edit rules. 6 Rollback if a failure occurs. If at the end point there is an error, there is an automatic rollback to the initial point.

33.1 Invoking Operations

Operations are invoked in one of the following ways: Individually online/batch From a block in a form From a DBCOBOL or DBPL1 program Through a query (either online or batch) From a rule From a BC client or an XML inbound document (via operation methods)

33.2 Operation Design

Each operation design is based on an existing physical design or on an existing operation design for the concept. An operation design can be used to present a subset of the fields included in a physical or operation design. Your application may require that a concept appear more than once, and that it be presented differently in each case. You can define several different operation designs for a concept so that the concept can be viewed in several different ways. Note that default designs
33-2

Operations and Operation Methods Operation Design

automatically created by Modeler are always physical, and cannot be changed to operation designs. The following should be considered for any operation design:

Design Number and Name

The number and name identify a design relative to a concept. A concept can have more than one design.

Dynamic Option
Assigning the Dynamic option determines what happens to an existing design when you add fields to the concept.

When Dynamic is assigned to a design, any fields you add to the concept are also added automatically to the design. When Dynamic is not assigned to a design, and you add fields to the concept, you must explicitly add the fields to the design, if you want them to appear in this design.

The main design must have the Dynamic option assigned. For a design which has been assigned IdentifierOnly, Dynamic has no effect.

IdentifierOnly Option
By default, the IdentifierOnly option is not assigned and all the fields defined for the concept exist in the design. Assigning the IdentifierOnly option defines a design that contains only the Key and Name fields. After the design is created, any other fields that you may need can be added. The following should be considered for any design:

Implementation Option
Assigning the Implementation option indicates that the design is implemented when the concept is implemented. Implementation is not assigned by defaultto give you a chance to create the design the way you want before implementing it. Several designs can be implemented for a particular concept.

33-3

33

Operations and Operation Methods Defining a New Operation

The following points should be noted:

If you wish to build a design but not implement it at this point, do not assign Implementation. If you are defining a design for a concept that is not yet implemented, and you assign Implementation, the design is implemented only when the concept advances to the implementation stage. If you are defining a design for a concept that is already implemented, the design is implemented only after you explicitly assign the Implementation option.

If you have an implemented design, and you unassign Implementation, the data structures generated for the design are removed from the knowledgebase.

Which Fields are Used

By default, when a design is created, all the fields in the concept and the parent concept are included. Any fields that are not needed can be deleted after the design is created. The Fields groupbox allows you to delete fields from a design and to add or delete non-key fields of the concept and of its parent concepts. When the IdentifierOnly option is assigned only the key and name fields initially exist in the design.

33.3 Defining a New Operation

On implementing a concept, an operation is automatically created to access the data. If you want to define an operation, other than the default operation you receive when implementing a concept, create a new design for the concept that has OperationOnly assigned.

33-4

Operations and Operation Methods Defining a New Operation

To define a new operation:

1 From the Model, right-click the concept and choose Object > Concept Design from the pop-up menu that is displayed. The Concept: Design form is displayed:

2 Right-click in the Design textbox. Choose NewDesign from the pop-up menu that is displayed:

33-5

33

Operations and Operation Methods Defining a New Operation

The Concept: New Design form is displayed:

33-6

Operations and Operation Methods Defining a New Operation

3 Enter a name and number for the design in the Design textboxes. 4 Assign OperationOnly. The resulting concept design definition is an operation definition. A new concept definition is not created. 5 If the new operation design is based on an existing physical design, choose the number of the physical design from the Referred Design dropdown listbox. By default, a design is based on the main design. Therefore, if you do not specify a design number, Modeler enters the main design as the Referred Design. If the operation design is copied from an existing operation design, choose the number of the existing operation design from the From Design dropdown listbox:

33-7

33

Operations and Operation Methods Specifying an Operation Design Without a Target

The Referred Design field automatically displays the number of the physical design on which the From Design is based. 6 You do not need to include all of the concept fields in the operation design. Also, you can include fields that are part of a parent concept. The key fields are automatically included, whether you define them or not. Customize the fields for the new operation design:

To obtain all fields for the concept, click Apply. Remove any concept fields you do not want in the new operation design, by locating the pointer on the field and clicking Delete. To obtain only the key fields, assign the IdentifierOnly option. Choose any concept fields to add to the operation from the drop-down listbox for the Field textbox. Add parent fields that you want to appear in the operation by entering the field name in the Field textbox and the parent name in the Source Concept textbox.

33.4 Specifying an Operation Design Without a Target

When an operation design is implemented, by default an operation with a target is generated, but no new physical structure is created. An operation is used to access the enterprise layer. A concept design is specified as an operation design by assigning the OperationOnly property to the design. The operation generated for the concept design can be generated without a target by assigning to the concept design the OperWithoutTarget property. An operation without a target does not directly update an object in the knowledgebase (since it has no target object). The logic (rules) associated with such an operation is used in business logic processes. For example, form flow can be controlled by such an operation, as well as other decision making processes. The following applies to an operation design without a target: The Referred Design for such an operation concept design can only be a physical design. All fields, except path fields, from the referred physical design are automatically defined for the operation design. Path fields (like any other field from a parent concept) must be specified manually. An implemented operation concept design without a target cannot be changed from an operation design to a physical design. An implemented physical design cannot be changed to an operational design without a target.
33-8

Operations and Operation Methods Customizing an Operation

A concept design without a target that has not yet been implemented can be changed from an operation design to a physical design or from a physical design to an operation design by assigning and unassinging the appropriate properties.

The OperWithoutTarget property cannot be assigned to a physical design.

To specify an operation design without a target: Access the Concept Design form and assign the OperWithoutTarget property to the operation design:

33.5 Customizing an Operation

To customize an operation:

1 Access the Operation Definition form by double-clicking the operation listed under Operations on the Logic tab of the Navigation pane of Development Workbench.

2 Select the operation field to be customized and assign properties to the field from the Properties pane:

33-9

33

Operations and Operation Methods Customizing an Operation

Assigning Field Properties

Fields defined in the operation, that do not exist in the concept, must be assigned one of the following properties: DefaultSubject Take the value from the subject concept. This value can only be used if a preceding field is the subject concept's key field. NoInput The field is defined in the operation only and not in the concept. A field is usually defined with this property when it is required for referencing by rules. This is analogous to defining a virtual field. A field, with this property assigned, does not need to be previously defined in any other concept. That is, it does not need a source concept. VerifySubject Verify the value entered via the operation against the value in the subject concept. This property can only be used if a preceding field is the subject concept's key field. The field must be defined in the subject concept, either with Name or VerifyInClass property assigned. If the field is defined in the subject concept with Name, VerifySubject is used to verify the value defined the field against its code (the subject key
33-10

Operations and Operation Methods Customizing an Operation

value). That is, if both a value for this field and the code are entered, then the two are checked against each other. If only the value is entered, then the coded value for this value is also displayed. If the field is defined in the subject concept with VerifyInClass, VerifySubject role is used to verify the value defined for the field against its corresponding value in the subject concept. See the General Reference for further details about these options. Only an operation and the default data forms are generated for the concept definition (i.e. the internal database structuresfields, class, compositeare not created).

The operation is equivalent to an SQL view of the concept.

Stopping User Access to a Field

Assign NoInput to the field in the operation. This prevents access to the field in every form where the operation is included. Compare with Protected, which is form dependent (i.e. it only applies to the field in the specific form).

Insuring That a Value is Entered to a Field

Assign MustInsert to the field in the operation. MustInsert Insures that a value exists for the field when the user inserts or changes a new occurrence.

If you assign Name in a field in the concept definition, MustInsert is automatically assigned to the field in the operation definition.

MustAppear Insures that a value exists for the field when the user inserts an occurrence.

Including a Field in an Operation Not in a Concept

Fields used for presentation purposes only (e.g. fields that are used to display a calculated value) can be included in an operation even though they are not included in any concept definition.

To define a field in an operation only:

1 From the Model, right-click the concept that is the target for the operation. A pop-up menu appears. Select Object > Fields. The Concept form is displayed.
33-11

33

Operations and Operation Methods Modifying an Existing Operation Design

2 Define the field that you want to appear in the operation in the position you want (among the fields defined for the concept). 3 Assign the NotInClass property to the field. The field is defined in the operation only and not in the concept. A field is usually assigned this property when it is required for referencing by rules. This is analogous to defining a virtual field. A field with the NotInClass property assigned does not need to be previously defined in any other concept. That is, it does not need a source concept. 4 Click OK. A field definition is created in the knowledgebase, that is included in the operation definition generated for the concept.

Not Displaying the Parent Block

When displaying a form based on an operation design for a dependent concept, the parent fields are also displayed on the form in a parent block. You can customize the display, and not display the parent block by choosing NoParentBlock for the Parent Display property.

33.6 Modifying an Existing Operation Design

You can view and modify the definition of an operation existing design.

To modify an existing operation design:

1 Right-click the required concept (in design or implementation stage) and choose ObjectConcept Design. The Concept: Design (2013) form opens, displaying the main design for the concept. 2 Right-click with the pointer in the Design textbox. Choose All Concept Designs from the pop-up menu that is displayed.

33-12

Operations and Operation Methods Modifying an Existing Operation Design

The Concept: All Designs form is displayed listing the existing concept designs:

3 Right-click with the pointer on the required operation design and choose Detail from the pop-up menu that is displayed. The Concept: Design Definition form is displayed:

33-13

33

Operations and Operation Methods Operation Design Example

4 Make any modification you need and click OK.

33.7 Operation Design Example

A physical design exists for a policy holder model for a claims department of an insurance company that includes the following entities:

The model performs the following services for the department: Policy Accounts Claims Lists all policies for a policy holder.

Lists all claims for a policy.

Each of these functions involves the PolicyHolder entity shown in this concept model:

33-14

Operations and Operation Methods Defining a Banner Operation

Policy Agent

The policy agent needs all the fields of the Claim weak entity and only some of the fields of the PolicyHolder entity. An OperationOnly design can be created for the PolicyHolder entity which contains only the required fields. An operation design can be created for the Claim weak entity and linked to the new operation design of the PolicyHolder entity.

33.8 Defining a Banner Operation

A banner operation is an operation that replaces the default parent concept operation in every form where the parent concept is displayed together with multiple occurrences of a dependent concept. Example: The Address field in the PolicyHolder concept is not required in the data entry forms generated for dependent concepts. By default the Address field is included in the generated multiple occurrence data entry form for the dependent concept. By defining an operation design for the
33-15

33

Operations and Operation Methods Defining a Banner Operation

PolicyHolder concept that does not contain the Address field and assigning the banner option to the operation design, a banner operation is created for the parent (PolicyHolder) concept that does not include the Address field. The field is excluded from all of the multiple occurrence forms generated for dependent concepts of the PolicyHolder concept. The following is the default form for the PolicyAccessor concept (based on the default operation for the parent, i.e. including all the fields from PolicyHolder):

33-16

Operations and Operation Methods Defining a Banner Operation

The following is the form based on the parent banner operation. Note that the Address field is no longer displayed.

To define a banner operation:

1 From the Model, right-click the concept for which you want to define a banner operation and choose Object > Concept Design from the pop-up menu that is displayed. The Concept: Design (2013) form is displayed. 2 Click NewDesign. The Concept: New Design (2009) form is displayed.

Enter a name and number for the banner design in the Design textboxes Assign OperationOnly to the design. Choose Banner for the Design Use property

33-17

33

Operations and Operation Methods Defining a Banner Operation

3 Click OK. When the dependent concepts are implemented (again) the banner operation is displayed on the data entry form together with the multiple occurrences of the dependent. A banner operation for the parent concept should be defined before any dependent concepts are defined (or implemented). To define a banner operation for a parent having an implemented concept hierarchy (parents and dependent concepts) or to modify an existing banner operation, retreat all the dependent concepts to the Design stage and then define or modify the banner operation for the parent concept. A banner operation can be defined for any concept in the concept hierarchy. When a banner is created for a concept that has a hierarchy of dependent concepts, the banner operation is only displayed on the data entry form of the immediate dependent concept. Data entry forms for the other dependents, display only the key and name fields for all parents other

33-18

Operations and Operation Methods Processing Operations in Groups

than the immediate parent (for the immediate parent the banner operation is displayed).

33.9 Processing Operations in Groups

Operations are processed serially, in the order that they are read by the Business Logic Processor.

When operations are processed online, all the operations processed are accepted, until an operation fails. An operation read after the operation failed is not processed. Updates to the database that were made via operations that were accepted prior to the operation that failed remain. When the operations are processed in batch, all the operations in the run are processed, including any operations read after an operation that failed.

If you want the acceptance of operations to depend on whether another operation succeeds, group the operations together. Once grouped together, if one operation in the group fails, none of the operations are accepted. The operations in the group can be of different types (i.e. the operation numbers can be different).

Defining a Default Value for a Field in an Operation

You can define a default field value for a field in an operation. A default value defined on a field in an operation overrides any default value set on the field. The default value is used in every form that includes the operation definition.

To define a default value for a field in an operation:

1 From the Model, right-click the concept and choose Object > Concept Design. The Concept: Design (2013) form is displayed. 2 With the pointer in the Design textbox, right-click and choose All Concept Designs from the pop-up menu that is displayed. The Concept: All Designs (2043) form is displayed. 3 Click on a particular Design. Right-click in the particular Design textbox and choose Detail form the pop-up menu that is displayed. The Concept: Design Definition (2027) form is displayed.

33-19

33

Operations and Operation Methods Deleting an Operation

4 Right-click in the Design textbox and choose Operation form the pop-up menu that is displayed. The Constructor: Operation Definition (100403) form is displayed listing the operation definition:

5 Click on a particular field. 6 Enter a default value (hexadecimal) for the Default (in Hex) property. 7 Assign the keepDefault property to the field. When KeepDefault is assigned to a field in the operation, the default value is used when no value is assigned to the field.

33.10 Deleting an Operation

An operation can be deleted, but care must be exercised since an operation may have forms, actions or other objects that use it. If the operation is not in use, you can delete the operation via the Operation Definition form. If the operation is in use, you must locate the objects using the operation and remove the use.

You can check for objects that use the operation by right-clicking in the Operation No or Name textbox and choosing Objects Where Included from the pop-up menu that is displayed. Then choose the appropriate object (e.g. forms, queries, components) respectively.

33-20

Operations and Operation Methods Using Synonyms

33.11 Using Synonyms

A synonym is given automatically to an operation upon operation definition unless the NoAutoSynonyms option has been defined for the database. The automatically defined synonym consists of the letter T concatenated with the unique operation number. Example: For an operation with Operation Number 3000, the automatically defined synonym for the operation is: T3000. You can also define your own synonyms for an operation.

To define synonyms for an operation:

1 Via Modeler, right-click the concept and choose Object > Concept Design. The Concept: Design form for the concept is displayed. 2 Get to the correct design and click Operation. The Constructor: Operation Definition (100403) form is displayed. 3 Click in the Operation No or Name textbox. 4 Expand the Synonyms property and click in the No textbox. Click Add to add a new synonym. Enter a new synonym for the operation in the subsequent textbox that is displayed. 5 Click OK.

You can keep the automatically defined synonym unique by not defining your synonyms or naming objects with the automatic synonym naming convention.

33.12 Rulesets Triggered by Operations

There are two kinds of rulesets that can be attached to an operation: issue or edit. Issue Rulesets that are executed (triggered) when an operation is issued, before the operation (insert, change, edit etc.) is performed and before edit rulesets are executed.

A derivation rule is only triggered for an operation that has no target. However, an immediate derivation is also triggered for an operation that has a target.

The following operations are recorded in the Journal:

Operations with targets that have issue rulesets attached to them. Operations without targets that have issue rulesets attached to them if they successfully execute derivation rules.

33-21

33

Operations and Operation Methods Operation Methods

If you want an issue ruleset to be executed when the Journal is run (e.g. during a restore), assign the OnJournal option to that issue ruleset. When OnJournal is assigned, all the rules defined for the ruleset are executed when the Journal is run. If you do not want all the rules to be executed, put the rules that you want executed in an issue ruleset with the OnJournal option assigned, and put the others in an issue ruleset without the OnJournal option assigned. Example: If an issue ruleset includes derivation rules, fetch rules, and computation rules, and you only want the derivation rules executed when the Journal is run, make two rulesets. In one, put the derivation rules and assign the OnJournal option to the ruleset. In the second, put the other rules and do not assign the OnJournal option. Edit Rulesets that are executed when an editing operation is performed; i.e. when an operation issued with the Edit operation code or when scrolling on the block is done (using the Backward or Forward buttons).

An edit ruleset cannot be run in batch, because the function of an edit ruleset is to enhance the presentation of the data on a form.

33.13 Operation Methods

An operation that is defined as a ByMethod operation can use operation methods. Operation methods enhance the functionality of an operation. They allow more precise control over the way an operation accesses requested information. Specifically, they allow the application developer to define specific methods instead of using operation codes. There are create, retrieve, modify and remove operation methods. Retrieve methods access information via rulesets that execute fetch and validation rules. All other methods (i.e. create, modify and remove) access information via their operation directly on the BLP. An operation method is used when accessing an operation via a component or via an XML inbound document. There are two categories of operation methods: Built-in methods User-defined methods An operation method contains: implementation ruleset input parameters output parameters sort fields
33-22

Operations and Operation Methods Operation Methods

method properties

Implementation Ruleset
An implementation ruleset is only used with find methods: For a built-in operation method a built-in implementation ruleset is supplied. For a user-defined operation method an implementation ruleset is defined by the user. The ruleset can contain: fetch or fetchSQL rules used for retrieving data from a class validation rules used for validating the input fields and for filtering the results initiation rules (executed once) on method activation. The ruleset is triggered upon invoking the method and a series of rules are executed to perform the requested operation.

Input Fields
Each method has a list of input fields. The input fields are used as input for the WHERE and SORT clauses of the fetchSQL rule that implements the operation method and for filtering the size of the results. The input fields can be any of the following: fields of an operation system Global fields (field number range from 1 to 100, computed by the BLP) control global fields RowCountercontrols the number of occurrences returned. The RowCounter global field must be defined as input for a user-defined method that has a multiplicity of many. For a built-in method it is added automatically. application context fields Context, Session, RequestContextcontext fields computed via an issue rule user global fields

The following are the input field properties: Fieldthe unique eMerge identifier for the field and the field name. Impliedindicates that these fields obtain their values from method parameters at runtime or are given a value by the application. Application context fields are automatically defined as Implied fields and their value cannot be changed by the user. The user can however, define operation fields as Implied fields.
33-23

33

Operations and Operation Methods Operation Methods

For Implied fields one of the following options is assigned: Fixed valueThe value specified is used as input and can not be changed by the application Initial valueThe value specified is used as input Space valueThe value of the field is a space character. EmptyThe value of the field is empty. Allowed Nullindicates that a value doe not have to be specified for these fields. Fields that are not defined as Implied fields can be defined as Allowed Null fields. All other fields that are neither Implied fields nor Allowed Null fields must have their value supplied by the user. Set/GetIndicates that the field value is stored/retrieved from the context. EqualIndicates that only instances matching the key or partial key are retrieved. Context TypeSpecifies in which context the input value is restored/stored: ControlIndicates that the field value is used to control the amount of data retrieved by the method (can only be defined for Row Counter field (2796)). Requestindicates the field is set/get to the Request context. Sessionindicates the field is set/get to the user context. SystemGlobalindicates the field is retrieved from a Global field (fields 1-100). Request&Systemindicates the field is set to the updatable Global field (i.e. PostRC, field (37) and ReturnedAction field (15)).

Output Fields
The output fields of an operation method are: All persistent fields of the operation. Class fields that are not defined in the operation but have the Concurrency Check option assigned. Fields that are not defined in the operation but have Data Privacy and Down Privacy assigned. Fields that are not defined in an operation but are used in an edit rule. Behavior of output fields: Fields that are defined in the operation but are not retrieved via a fetch rule, are returned with an empty value.

33-24

Operations and Operation Methods Built-in Operation Methods

Sort Fields
A Sort field has the following properties: Sequence Numberindicates the sorting order. Descending/Ascendingindicates the sorting type. These fields are view only.

Method Properties
The following are the method properties: NameThe name of the operation method. The name is unique for a given operation. MultiplicityZero, One or Many Indicates if the method returns none, one or more occurrences. Update methods have a multiplicity of Many. TypeThe type of method (e.g. retrieve or update) AutoInvoke CandidateA component method assigned the AutoInvoked option can only be implemented via an AutoInvoked Candidate operation method. Key and partial key fields assigned Equal must be specified in the order defined in the target. ImmediateIndicates that the operation method only affects the cache. When a component create method is based on an immediate operation method, a component is created immediately in the cache. The method does not affect the database. No implementing rulesets are executed.

33.14 Built-in Operation Methods

A set of built-in operation methods is supplied by eMerge when defining an operation as a ByMethod operation. The set includes all basic requests that are supported by the BLP engine. You can select a subset of these built-in methods for your operation. List of built-in methods: Method Name Create Modify Remove Parameters All operation fields that can be updated All operation fields that can be updated All key and path fields

33-25

33

Operations and Operation Methods User-defined Operation Methods

Method Name FindByKey FindByPartialKey FindByPartialKeyDesc FindGreaterOrEqual FindGreaterThan FindLessOrEqual FindLessThan FindByParent FindByParentDesc FindByPartialKeyByParent FindByPartialKeyByParentDesc FindGreaterOrEqualByParent FindGreaterThanByParent FindLessOrEqualByParent FindLessThanByParent FindByKeyAndFields FindByPartialKeyAndFields FindByPartialKeyAndFieldsDesc

Parameters All key and path fields All key and path fields All key and path fields All key and path fields All key and path fields All key and path fields All key and path fields All key and path fields All key and path fields All key and path fields All key and path fields All key and path fields All key and path fields All key and path fields All key and path fields All key, path, and attribute fields All key, path, and attribute fields All key, path, and attribute fields

The following applies to built-in methods: They cannot be updated (not fields, properties, or rules) or recompiled. If an update is needed, a user-defined method must be defined based on the built-in method and updated as required. The implementation ruleset can not be called from another rule. It can be called by another method. Find methods for a temporary operation are generated without an implementation ruleset.

33.15 User-defined Operation Methods

You can define your own operation method to fulfill any special needs (such as a fetch with a complicated condition). The following are the ways to specify your own method: overriding and customizing an existing built-in method copying and customizing an existing built-in method
33-26

Operations and Operation Methods User-defined Operation Methods

defining a new operation method calling an existing built-in method

Copying and Customizing Operation Methods

Override BIM A built-in operation method can be overridden by assigning the Override BIM option. When a find built-in method is overridden, a copy of the input fields and the implementation ruleset are created. The copied implementation ruleset can be updated. The copied input fields can not be updated. This enables defining a user-defined operation method for retrieve that has the same input fields as the overridden built-in method but that uses a user specified implementation ruleset. When Overrride BIM is used for an update, the input fields can be changed. An operation method can be overridden by assigning the Called option. This enables defining a user-defined operation method that has the same implementation ruleset as the called built-in method (or another userdefined method) but whose input field property values can be changed. A find operation method can be copied to a user-defined operation method. When a findoperation method is copied, a copy of the input fields and the implementation ruleset are created. The copied implementation ruleset as well as the copied input fields can be updated. This enables defining a user-defined operation method for which both the implementation ruleset and the input field values can be changed.

Called

Copy

Immediate Operation Methods

A create operation method can be defined as immediate when: It has no target The target is a temporary composite When an immediate method is executed (by a BC client or from an XML document): When it has no targeta component instance is created in the context When the target is a temporary compositea component instance is created in the context. The immediate operation method does not impact the database. The composite is also created but rules are not triggered

33-27

33

Operations and Operation Methods Defining an Operation Method

33.16 Defining an Operation Method

To define an operation method:

1 Via the Logic tab of the Navigation pane of Development Workbench, right-click Operations and either open an existing operation or define a new operation. The Operation Definition form is displayed:

2 Assign ByMethod to the operation. The following applies to a ByMethod operation: ByMethod can not be assigned: For the generation of a target class having an non-unique key If one of the fields appears more than once in the operation After ByMethod is assigned to an operation, deleting/inserting of the target is not allowed A ByMethod operation can not be deleted until all methods are deleted

3 Click Methods. The Operation Methods form is displayed.

33-28

Operations and Operation Methods Defining an Operation Method

4 When Temporary is assigned, operation methods are created without an implementing ruleset. Temporary is automatically assigned for an: operation without a target operation with a temporary targetDoes not affect the database. Can be unassigned before any method is defined. 5 FetchSQLImplement is automatically assigned for an operation with an SQL target. When FetchSQLImplement is unassigned, the generated implementation rules are fetch rules and not fetchSQL rules. 6 To store keys in the Request context, assign Store Keys and enter, in the first textbox, a number for a ruleset to contain rules to perform the store. The ruleset is automatically populated with rules by eMerge. 7 If contiguous keys are being used, assign Contiguous Keys and enter, in the first textbox, a the number for a ruleset to contain rules to perform contiguity checking. The ruleset is automatically populated with rules by eMerge. The contiguity of the keys is then automatically checked.

33-29

33

Operations and Operation Methods Defining an Operation Method

8 Define user-defined methods via the User-defined Method table control. See "Defining User-defined Methods". 9 Define built-in methods via the Built-in Method table control. See "Defining Built-in Methods". 10 Right-click with the pointer in the Implementing By textbox and choose Details. Thee Ruleset Review form is displayed:

The following applies to a user-defined implementing ruleset: One (and only one) of the rules in the ruleset must be assigned the MethodImplementation option. Any rule in the ruleset can be assigned MethodInitiation except the rule that is assigned MethodImplementation. When the method is repeatedly invoked (fetch repeated), the rules assigned MethodInitiation are executed only once. 11 Click RecreateBIM to automatically recreate all selected built-in methods (i.e. to reset the implementing ruleset to the supplied implementing ruleset for the find method). This is useful when the implementing rules are modified.

Defining User-defined Methods

A user-defined method can be:

Based on an existing built-in method Defined as a new user-defined method

33-30

Operations and Operation Methods Defining an Operation Method

To base the user-defined method on an existing built-in method: Do one of the following:

Select the number of the built-in method from the Override BIM dropdown listbox (to override the ruleset implementation). Select the number of the built-in method from the Called Method dropdown listbox (to override the input field values) Copy any existing method.

To define a new user-defined method:

1 Enter the name for the new user-defined operation method in the Userdefined Method textbox:
Before defining a method for an operation without a target, click DefineKey and update the Role for those fields that serve as Key fields.

2 Right-click the method name and select Details from the popup menu that is displayed. The Operation Method Definition form is displayed:

33-31

33

Operations and Operation Methods Defining an Operation Method

3 Change the Multiplicity if necessary. When Multiplicity is One, all key and path fields are assigned the Equal property. 4 Customize input fields for the operation method: Row Counter is the maximum number of occurrences retrieved for a find method with Multiplicity Many. For Multiplicity One, the default is 1. For Multiplicity Many, the default is 0 (i.e. returns all matching occurrences). Fieldthe unique eMerge identifier for the field and the field name. Impliedindicates that these fields obtain their values from method parameters at runtime or are given a value by the application. Application context fields are automatically defined as Implied fields and their value cannot be changed by the user. The user can however, define operation fields as Implied fields. For Implied fields one of the following options is assigned: Fixed valueThe value specified is used as input and can not be changed by the application Initial valueThe value specified is used as input Space valueThe value of the field is a space character. EmptyThe value of the field is empty. Allowed Nullindicates that a value doe not have to be specified for these fields. Fields that are not defined as Implied fields can be defined as Allowed Null fields. All other fields that are neither Implied fields nor Allowed Null fields must have their value supplied by the user. If Allowed Null is not specified for the field, and in addition, the field value is not specified in any way, a runtime error occurs. EqualIndicates that only instances matching the key or partial key are retrieved. Set/GetIndicates that the field value is stored/retrieved from the context. Context TypeSpecifies in which context the input value is restored/stored: ControlIndicates that the field value is used to control the amount of data retrieved by method (can only be defined for Row Counter field (2796)). Requestindicates the field is set/get to the request context. Sessionindicates the field is set/get to the user context. SystemGlobalindicates the field is retrieved from Global field (fields 1-100). A SystemGlobal field must be assigned Implied or Get.

33-32

Operations and Operation Methods Defining an Operation Method

Request&Systenindicates the field is set to the updatable Global field (i.e. PostRC, field (37) and ReturnedAction field (15)).

5 Click OK to save the data and to return to the Operation Method Definition form. 6 Select or enter an implementing ruleset for the operation in the Implemented By textbox. 7 Right-click with the pointer in the Implementing By textbox and choose Details. Thee Ruleset Review (100751) form is displayed:

The following applies to a user-defined implementing ruleset: One (and only one) of the rules in the ruleset must be assigned the MethodImplementation option. Any rule in the ruleset can be assigned MethodInitiation except the rule that is assigned MethodImplementation. When the method is repeatedly invoked (fetch repeated), the rules assigned MethodInitiation are executed only once. 8 Select or enter rules for the implementing ruleset. 9 Zoom on the rule and assign the MethodImplementation option to the rule:

33-33

33

Operations and Operation Methods Defining an Operation Method

10 To improve performance, specifyfor the FindAction propertythe action that represents a DBMS call. Decoding, encoding and verification with subject is done in SQL or via rules. See the fetchSQL rule syntax for details.

Defining Built-in Methods

Via a Template A built-in methods template defines a set of built-in methods. See "Defining a Built-in Methods Template" (see below) for information on how to define a built-in methods template 1 From the Operation Methods form, select a built-in methods template in the Built-in Methods Template field. If a default template is not defined, the All Operation Built-in Methods (1) template, which contains all available built-in methods, is used as the default template. 2 Click the CreateBIM button. A set of built-in methods are brought into the Built-in Method table control. From a List 1 From the Operation Methods form, click the dropdown listbox in the Builtin Method column. 2 Populate the tablecontrol by selecting any required built-in methods. The number is filled in automatically after a built-in method is selected.

33-34

Operations and Operation Methods Defining an Operation Method

Defining a Built-in Methods Template

A built-in methods template defines a set of built-in methods that are brought into the definition of an operation method via the CreateBIM button on the Operation Methods form (see "Defining Built-in Methods" above.)

To define a built-in methods template:

1 Via the Logic tab, right-click the Built-in Method Templates node. 2 The Built-in Methods Template Definition form is displayed:

3 Enter a number and name for the template in the Template No. and Name fields. Numbers 1-100 are reserved for the Pure. 4 Assign the DefaultTemplate option if the template is the default template for the database. If no default template is defined, the All Operation Builtin Methods (1) template, which contains all available built-in methods, is used as the default template. 5 Populate the tablecontrol by selecting any required built-in methods from the Built-in Method column. The number, Type and FindAction are filled in automatically after a built-in method is selected.

33-35

33

Operations and Operation Methods Defining an Operation Method

33-36

Part E

Presentation

Chapter 34 What is the Presentation

The application forms and the flow between the forms make up the presentation. The user enters and retrieves data via the presentation. This chapter explains how to plan the presentation, the different types of forms that can be used, and how to use Form Editor to create, edit and enhance forms.

34.1 Planning the Presentation

To lay out the presentation in a logical, useful manner, you must plan the following:

Data Objects to be Accessed

Decide which data objects are accessed via the forms.

End User Display Type (i.way or 3270 Terminals)

You must decide if the forms are to be accessed via i.way or via 3270 terminals. To create i.way forms, you use Form Editor. The forms for i.way can take advantage of the benefits of the i.way-based display. Forms that are to be accessed via 3270 terminals are defined via the Form Definition form accessed via the navigation pane:

34-1

34

What is the Presentation Building an Application

Flow Between the Forms

The user can access a form directly or through a flow. It is recommended that you provide access to forms via a form flow (using menus, tree compound forms, select and detail forms, and form actions), and that you not allow the user to jump directly to a form. Via the flow, the user can have access to values that are transferred from form to form.

34.2 Building an Application

Once you have determined which forms are needed, you can begin creating your forms using Form Editor. The forms you create to be part of your application can be of the following types:

data menu tree compound select and detail

The forms supplied to develop an application (the eMerge forms), and the forms you create as part of an application (the application forms) are all one of the above types.
34-2

What is the Presentation Types of Forms

To help create all the forms needed for an application, use a form template. A template is a model form on which you can base application forms. Each form that has a template assigned starts off with the options assigned to the template. You may then modify the individual form when and where necessary. Using a template for forms:

Enables all forms to have the same "look and feel" with minimum effort; i.e. templates can be used to set a standard look for an application. Greatly reduces the number of modifications needed to make to individual forms, therefore speeding up the development process. Enables leveraging the work put in to create and define blocks, operations, form actions, color, background, font, etc. from one form to another.

The following chapters describe all that can be done to and for an application form. Once you have an understanding of what is possible, create a template (See "Form Templates" on page 43-1.) and then begin to build your forms based on a template or even a set of templates.

For applications with more than one language, certain characteristics of the form may be made language dependent. See "Checking Language-Dependent Forms" on page 62-19 for details.

34.3 Types of Forms

Data Form
The end user enters data into a data form. The following example is a form with one multi-occurrence block: The following are two forms for the Employee concept:

34-3

34

What is the Presentation Types of Forms

single occurrence form

This form has one single-occurrence block:

multioccurrence form

This form has one multi-occurrence block:

The following figure shows the main parts of a data form. The form has a single-occurrence block, a multi-occurrence block (a TableControl block),

34-4

What is the Presentation Types of Forms

a tab control (with three tab pages; Tab Page A is the active tab page), form actions, text, a line, and an image. text

form name form number first block

second block (TableControl block)

an occurrence

tab control (with 3 tab pages)

active tab page line image form actions The name and number of the form are displayed in the title bar of the window. A data form can include one or more data blocks. A block contains one or more sets of fields. Each set of fields is an occurrence.

Form Name and Number Block

34-5

34

What is the Presentation Types of Forms

In the example above in the first block, there is one occurrence of a set of fields. In the second block, there are multiple occurrences of each set of fields in a TableControl block. In the first block the field names are on the same line as the field values. In the second block the field names appear above the field values (called TitlesOn). A block can be one of three types:

An operation which passes a set of fields between an implemented concept and a form. A query to be invoked A program to be invoked

See "Defining a Block" on page 35-4. Tab Control A tab control enables the display of a set of forms as a set of tab pages within the same area of one data formthus optimizing form area usage and leading to better organization of information. In the example above in the third block, there is a tab control for three called forms: Tab Page A, Tab Page B, and Tab Page C.

Each tab page is assigned to a particular form (i.e. its called form). The called form can contain more than one block. Each tab page has a tab that contains a label and, optionally, an icon. The set of tab pages within a tab control can be formatted as a whole or each tab page can have its own formatting; e.g. color, font. All called forms of one tab control are included in one unit of work.

See "Defining a Tab Control" on page 35-21. Form Action Each form can have a set of form actions. Form actions are used to access additional forms in the flow, or to complete the data entry process. Clicking a form action initiates a form-dependent action (e.g. another related form is accessed). A form action may be displayed as a button or graphical image. A form action can also be initiated by pressing the equivalent function key (e.g. <F1>, <F2>, etc.) or by choosing the equivalent item listed on a pull-down menu. See "Form Actions" on page 39-1. Form Enhancements Enhancements can be added to forms. Text can be used to display comments or instructions (see page 34-14). Groupboxes, rectangles, and lines can be added for emphasis or to divide up parts of the form (see page 34-18, page 34-17, and page 34-17, respectively). Images can be added

34-6

What is the Presentation Types of Forms

see page 34-23). Binary large objects (BLOBs) can be added as part of the data (see page 35-50).

Menu Form
In a well designed application, there is a logical order or flow for moving from one form to another. The movement from one form to the next can be directed by a menu. The menu is a list of options that are used to access forms or to perform actions: Menu Name Menu Number

Option Entry Box Text of Option Icon of Option

The menu form consists of a menu name and number, options, and action buttons. Each option can be displayed with an icon and text describing the option. A menu option is selected by clicking the icon or the text of the desired option. See "Menu Forms" on page 36-1.

Tree Compound Form

A tree compound form consists of two frames: One frame contains the tree form (i.e. the tree control) and one contains a data form. The tree compound form is used as the "top form" for an application. A list of items

34-7

34

What is the Presentation Types of Forms

is presented to the end user in a tree. The user can expand or contract the nodes to view or hide a list of sub-items: Tree Form Data Form

Tree Compound Form You can specify the layout for the forms in the tree compound form: horizontalthe called forms are placed one above the other. verticalthe called forms are placed alongside each other. See "Tree Compound Forms" on page 37-1.

Select and Detail Forms

For any relationship between two entities (including a dependency relationship), the key field and the name field of one entity can be used to access data from the other entity. That is, a foreign key field and a foreign name field are used to access a select form or a detail form containing data from the foreign entity. Select Form A select form is a multiple occurrence data form. On accessing the select form, all the existing values for the particular field are displayed. The user can select a value and return to the calling form.

34-8

What is the Presentation Using Form Editor

Detail Form

A detail form is a single occurrence data form. On accessing the detail form, details of the occurrence having the particular key field or name field are displayed.

See "Select and Detail Forms" on page 38-1.

34.4 Using Form Editor

In Development Workbench, Form Editor is the tool used by the developer to define and modify forms. Use Form Editor to modify the appearance of, and control interaction within, application forms by defining presentation components.

34-9

34

What is the Presentation Using Form Editor

Form Editor button

If the application is to be accessed via a 3270 terminal, use eMerge 3270 display features to tailor the form display. Refer to Part L eMerge Applications via 3270Display.

Throughout this manual the phrase "Using Form Editor" refers to this procedure for invoking Form Editor for a displayed form: To use Form Editor: 1 Display the form you wish to edit. 2 Click the Form Editor button on the toolbar. The form changes so that you can edit it and the Form Editor toolbars are displayed. You can begin to modify the display of the form; i.e. add blocks, a tab control, form actions, form enhancements, etc.

34-10

What is the Presentation Accessing Form Definition for a Form

3 To work with Form Editor, use the Form Editor toolbars (described in General Reference), or right-click the form or an object on the form to display an appropriate menu:

4 If you want to undo your changes before saving, click the Undo button. For more details about undoing changes see "Undoing Modifications" on page 34-32. 5 Save the changes by clicking the Save button at any time during the editing session. 6 When you have finished editing, click the Form Editor button to finish. You are asked if you want to save the changed form. Confirm the changes. The form is displayed as it is seen by the end user of the finished application.

34.5 Accessing Form Definition for a Form

Most editing for a form is done via Form Editor. However, some things can be done and information retrieved via the Form Definition for the form. If the form is to be accessed via a 3270 terminal, edit the form via the Form Definition for the form (see Part L eMerge Applications via 3270Display).

Or

To access Form Definition for a form:

1 Expand the Forms node on the Presentation tab in the navigation pane. 2 Right-click the needed form and choose Form Definition. The Form Definition for the form is displayed.

1 Using Form Editor, right-click the form and choose Form Definition. The Form Definition for the form is displayed.

34-11

34

What is the Presentation Selecting Form Objects for Editing

34.6 Selecting Form Objects for Editing

You can select a particular form object for editing while working within Form Editor. Information about the selected form object is displayed in the status bar. Right-click the form object to display a popup menu. The popup menu contains what you can modify for the particular object.

You can select several objects on a form together. Handles appear around each object that is selected. The handles of the first selected object in the multiselection group are black while the handles of the others are grey. If a block in the form is a multioccurrence block, you can select only the top row, because Form Editor treats all the block occurrences as one form object.

To select a group of form objects:

1 Point outside the objects. 2 Drag a selection rectangle around them. Even objects that are not completely within the selection rectangle are selected. To select objects one at a time: 1 Click the first object. 2 Hold down <Ctrl> and click each subsequent object.

34-12

What is the Presentation Moving Objects Around the Form

34.7 Moving Objects Around the Form

You can move any form object to another position on the form. You can also nudge a form object to a new position on the form. Nudging means moving the selected object one pixel at a time in a specific direction.

To move an object: Select objects together as a multiobject selection if you want them to keep their relative position to each other after the move. If the object is a field in a multioccurrence block then all the occurrences keep their relative position to each other after the move.

1 Select the object that you want to move.

2 Drag the selected object to the desired location. Take advantage of the information on the status bar about the position of the selected object.

To move an image or label on a form action:

1 Hold down <Shift> and click the image or label. 2 Drag the image or label by holding the <Shift> down while dragging to the desired location. To move a block: 1 Hold down <Shift> and click within the block. 2 Drag the block by holding the <Shift> down while dragging to the desired location. To move a form window: Point to the window title bar and drag to the desired location. To nudge an object on a form: Select objects together as a multiobject selection if you want them to keep their relative position to each other. If the object is a field in a multioccurrence block then all the occurrences keep their relative position to each other after the move. 2 Hold down <Ctrl> and press an <arrow> key. The selected object moves one pixel in the direction of the arrow key.

1 Select any object that you want to nudge.

34-13

34

What is the Presentation Adding and Modifying Text on a Form

34.8 Adding and Modifying Text on a Form

You can add text freely anywhere on a form. For example, the text can be within a block, above a block to label it, or on buttons. There are no limitations. You may also edit existing text on a form, modifying its content and style.

Adding and Editing Text

There are no limitations on where on the form you may add text.

To add text:

1 Using Form Editor, click the Insert Text button on the Edit toolbar. 2 Click the form and drag to define the text area and position. 3 Type the text. 4 Click somewhere else on the form to finish. You can also edit the text that is already on the form, such as field names.

To edit text:

1 Using Form Editor, click the text you want to modify and then click the Edit Text button on the Edit toolbar or right-click and choose Set Edit Text. 2 Edit the text. 3 To finish, click the Edit Text button again or right click and choose End Edit Text.

Modifying Text Style

The following text styles may be changed using the formatting toolbar buttons: Icon Font Bold Name Definition Enables the changing of font family, style and size. Changes text to bold.

34-14

What is the Presentation Adding and Modifying Text on a Form

Icon Italic

Name

Definition Changes text to italic. Changes text to underline.

Underline

Decrease Size by 1 Decreases the font size by one point. Increase Size by 1 Increases the font size by one point. Foreground Color Background Color Enables the foreground color to be changed. Enables the background color to be changed.

If the font size chosen makes the text so big that some of the text is not visible, make the object containing the text bigger by resizing. See "Resizing Objects" on page 34-29. You can only see a change made to the font of a field value if there is a value in the field before going into Form Editor or if you exit Form Editor. If you change the font or size of the font for a field name or other text, the frame may appear to be too small. You can fit the frame to the text using the Shrinkwrap facility.

34-15

34

What is the Presentation Adding and Modifying Text on a Form

To adjust the text frame to fit:

1 Using Form Editor, right-click the text you want to modify. The following menu is displayed:

2 Choose Shrinkwrap from the displayed menu. The frame is expanded to fit exactly around the text.

Font Formatting for Free Text Form Objects

Free text form objects can be formatted as a whole or by selected parts of the free text form object.

To format a free text form object as a whole:

1 Right-click the free text form object and choose Font. The Font dialog box is displayed. 2 Make any desired formatting changes, including font family, style (e.g. italic, bold) effects (underline) and size.

To format a part of a free text form object:

1 Right-click the free text form object and choose Set Edit Text. 2 Highlight the part of the free text that is being formatted. 3 Right-click the highlighted text and choose Font. The Font dialog box is displayed. 4 Make any desired formatting changes. Note the list of sizes for parts is smaller than the list of sizes when formatting the whole free text form object.

34-16

What is the Presentation Adding Lines

34.9 Adding Lines

Lines can be added on a data entry form for emphasis or to divide up parts of a data entry form. When a line or rectangle is located on top of an existing data object on a form, you can adjust the order (e.g. in front or in back) of the display for the line or rectangle, via the Order option.

Adding a Line To a Form

1 Click the Add Line button. 2 Click and drag in the form. A line appears. 3 Change the position, direction and length of the line by selecting the line (if its not already selected) and dragging its handles.

Customizing a Line on a Form

To customize a line: Right-click the line and choose the option you require to change the line: Line Style Choose the style of line you want; e.g. solid line, dotted, dashed. Line style can only be changed for lines of width 1 point. (If you change the line style of a line wider than 1 point, then its width is automatically changed to 1 point.) Line Width to 5). Choose the width of the line. The width is in points (from 1

34.10 Adding Rectangles

Rectangles can be added on a data entry form for emphasis or to divide up parts of a data entry form.

Adding a Rectangle to a Form

1 Click the Insert Rectangle button. 2 Click and drag in the form. 3 Change the position and shape of the frame by dragging its handles.
34-17

34

What is the Presentation Adding Groupboxes

Customizing a Rectangle on a Form

1 Right-click the rectangle and choose Frame Type. Choose the style of rectangle you want: Flat 3D The frame of the rectangle appears as a line. The rectangle appears to jut out with shadowing around it. The rectangle appears to jut into the form. The rectangle appears to jut out of the form.

JutIn JutOut

34.11 Adding Groupboxes

Groupboxes can be added on a data entry form for emphasis or to divide up parts of a data entry form. The groupbox has a label that is an integral part of the groupbox.

Adding a Groupbox to a Form

1 Click the Insert Groupbox button. 2 Click and drag in the form. 3 Change the position and shape of the groupbox frame by dragging its handles.
34-18

What is the Presentation Customizing Colors

Customizing a Groupbox on a Form

1 Right-click the groupbox. A popup menu is displayed:

2 Choose the menu option you need to customize the groupbox for your needs: Set Edit Text The text of the groupbox label. After you have finished editing the label, right-click the label and choose End Edit Text. Frame Type Flat The style of the groupbox:

The frame of the groupbox appears as a line. The groupbox appears to jut into the form. The color of the label and the frame.

Groove

Foreground Color Font

The size and font used for the label.

Reset Font Resets the size and font of the label according to the default formatting for the form.

34.12 Customizing Colors

The Administrator can customize the colors of the standard color palette or add custom colors that can be used in addition to the standard RGB color set. See the Business Integrity Server Administration Guide for more information.

34-19

34

What is the Presentation Changing the Colors of Form Objects

34.13 Changing the Colors of Form Objects

You can change the foreground and background colors of any object in a form. This can be done in two ways:

You can change the color for each form object type (e.g. all actions or all field names) on the form You can change the color for a specific form object (e.g. the first field name on the form)

You can only see a change made to the foreground of a field after you exit Form Editor or if there is a value in the field before going into Form Editor.

Changing Colors for Form Object Types

1 Using Form Editor, right-click the form and choose Default Formatting. The Default Formatting dialog box is displayed:

2 Select the form object type that you want to change from the Options group box. Example: Select Field Name to change the colors of all the names of fields in the form. 3 Select the specific item you want to change from the Description box. Example:
34-20

Foreground Color.

What is the Presentation Changing the Colors of Form Objects

4 Click the Change button. The appropriate Select Color dialog box is displayed:

5 Choose from the following color ranges: System the set of allowed colors a range of white, grey and black colors

Monochrome Custom

the custom colors currently in use in the database

The selected color is displayed in the New box. 6 Click OK for the change to take effect.

34-21

34

What is the Presentation Changing the Colors of Form Objects

Changing Colors for Specific Objects

1 Using Form Editor, select the object you want to modify.

Background Color Foreground Color

selected object

2 Choose Foreground Color or Background Color on the Form Editor Formatting toolbar. The appropriate Select Color dialog box is displayed:

34-22

What is the Presentation Defining Colors for the Field in Focus and Actions

3 Select the color you want from the System, Monochrome, Current Form, or Custom boxes: System the set of allowed colors a range of white, grey and black colors the colors currently displayed in the form

Monochrome Current Form Custom 4 Click OK.

the custom colors currently in use in the database

34.14 Defining Colors for the Field in Focus and Actions

The color of the foreground and background of the field where the insertion pointer is (i.e. the field in focus) and the foreground color displayed for a visited action (e.g. for a hyperlink when the cursor is passed over the hyperlink) can be defined via eMerge Client Administration global options. See eMerge Client Installation & Administration Guide.

34.15 Adding Images to a Form

An image can be added on a form or on a form action. The image used for the icon for a menu option or for a popup menu option can be changed. We recommend using RGB color mode rather than indexed color mode when creating the images to be added to a form. However, if you use indexed color, all the images should be from the same color palette or the same color lookup table. The files are stored in the <sapiens>\db directory. They are divided between those that are used in multiple applications and those that are used in a specific database. Common The image files that are used in multiple applications are stored in the <sapiens>\db\eObjects directory. Database The image files that are used with a specific database are stored in the <sapiens>\db\<catalogID><xx>\eObjects directory, where <xx> is the two-letter database identifier. Image files must be in .png or .jpg format.

34-23

34

What is the Presentation Adding Images to a Form

If an image is added to a form, the image is anchored to the form. Therefore, if it is placed in a block and the block is moved, the image does not move. If an image is added on a button, the image is anchored to the button. Therefore, if the button is moved, the image also moves. If the image is located on another form object, you can order the image (to place it in front or in back), by right-clicking the image and choosing the Order option.

To add an image to a form:

1 Using Form Editor, click the Insert Image button. 2 Click the location in the form where you want to place the image. The Open a File dialog box is displayed:

3 Choose the image file you want. The Open a File dialog box contains a preview image window. You can change the zoom mode for the images as they are inserted into a form.

34-24

What is the Presentation Adding Images to a Form

Mode Normal Size

Example The image is sized just as it is; i.e. there is no size adjustment for the preview image window. Thus, the preview image may be bigger or smaller than the preview image window.

No Stretch

The image is sized so that the image fits in the preview image window with the horizontalvertical image proportions are maintained.

With Stretch

The image is sized so that the image fits in the preview image window with the horizontalvertical image proportions not necessarily maintained.

34-25

34

What is the Presentation Aligning Form Objects

4 Click the Open button. The image is added to the form:

5 Drag the handles of the image to change its position, shape and size. You may need to reorganize your form after adding a large image.

34.16 Aligning Form Objects

You can align a form text objecta field title (with the TitlesOn option unassigned) or free textwithin its selection box and you can align several form objects together.

Aligning Several Form Objects

You can align a selected group of form objects with the first form object you select (the first colored object the figures below). Top/Bottom Alignment You align objects along a horizontal line by specifying the top/bottom alignment.

34-26

What is the Presentation Aligning Form Objects

Left/Right Alignment

You align objects along a vertical line by specifying the left/right alignment.

To align objects on a form:

1 Click the first object. The first object selected is used to align the group of objects. 2 Hold down <Ctrl> and click the other objects in the group. 3 Choose the type of alignment you want from the toolbar and click the appropriate alignment button: Align Top Align Bottom T/B Center Align Left Align Right L/R Center

If a form text objecta field title (with the TitlesOn option unassigned) or free textis right- or left-aligned together with other form objects, the text within the text selection box for the text object is aligned in the same direction as all the form objects. Example: Several form objectstext object plus other form objects are right-aligned:

the text object (selection box) is right-aligned together with the other form objects the text within the text selection box is right-aligned with respect to its selection box.

You can override the alignment of the text within its selection box by selecting only the particular text object and clicking either the Right Align or Left Align buttons.

34-27

34

What is the Presentation Adjusting Spacing Between Form Objects

Aligning a Single Text Object

A single form text objecta field title (with the TitlesOn option unassigned) or free textcan be aligned (i.e. right-aligned or leftaligned) within its selection box.

To align a single form text object:

1 Via Form Editor, select the form text object on the form to align.

2 Click the Align Right or Align Left buttons. The text is: right-aligned:

or left-aligned:

within its selection box.

In order to align text within a selection box make sure the selection box is wider than the text string.

34.17 Adjusting Spacing Between Form Objects

You can ensure that form objects are equally spaced vertically and horizontally.

To ensure equal spacing between form objects:

1 Click the first object. 2 Hold down <Ctrl> and click the other objects in the group. The space between the first two objects selected is used to determine the spacing between the group of objects.

34-28

Dont use the multiselection rectangle to select the group of objects when adjusting the space between objects.

3 Choose the type of alignment you want:

What is the Presentation Resizing Objects

Distribute Vertically spaced vertically.

Moves the selected group so the objects are equally

Distribute Horizontally Moves the selected group so the objects are equally spaced horizontally.

34.18 Resizing Objects

Resizing a Form Window
You can resize any form window via Form Editor to determine the size of the form when it is displayed. In addition, you can define if the end user can resize the form via the Modal, NoResize, NoMaximize, and NoMinimize options. If you make a form window so small that not all the form objects are displayed in the window, scroll bars are automatically added so you can see all of the form objects.

To resize a form:

1 Drag a window border to the size you want. 2 If you want to define if the end user can resize the form, right-click the form and choose Properties to access the Modal, NoResize, NoMaximize, NoMinimize and NoClose options.

Resizing a Single Object within a Form

You can resize any object within a form in Form Editor. A block cannot be made so small that the objects currently within the block would not show. If the Titleson option has been assigned to the block, the block cannot be made smaller; it can only be made bigger. If you make a field value so small that the whole value cannot be displayed at once, there is automatic scrolling so you can see all of the field value. If you make an image, line or frame too small, it appears as a dot.

To resize an object:

1 Select the object. Handles appear around the object. 2 Drag a handle to resize the object.
34-29

34

What is the Presentation Resizing Objects

When you resize a block, you can only use the right or bottom selection handles.

Making a Group of Form Objects the Same Size

A selected group of form objects can be made to be the same size. This may be done with field values, field names, text lines, images, lines or frames.

To resize a group of objects:

1 Select the first object. The size of the first object selected is used to determine the size of the subsequent objects. 2 Hold down <Ctrl> and click the other objects in the group. 3 Click the appropriate button on the toolbar: Make Same Height Matches the vertical size of all selected objects with the size of the first selected object. Make Same Width Matches the horizontal size of all selected objects with the size of the first selected object. Make Same Size Matches both the vertical and horizontal size of all selected objects with the size of the first selected object.

Making a Button and Its Image the Same Size

A button and the image that is "on" it can be made to be the same size.

To make a button and its image the same size:

1 Via Form Editor, right-click the button. A popup menu is displayed.

2 Choose Image > Make Same Width as Action. or choose Image > Make Same Height as Action. or choose Image > Make Same Size as Action. The image is resized to match the button, according to the menu option chosen.

To return the size of an image on a button to its original size: Via Form Editor, right-click the image on the button and choose Set Original Size from the pop-up menu.

34-30

What is the Presentation Assigning or Removing an Option for Multiple Fields

Making Two TableControl Blocks the Same Size

Two TableControl blocks within the same form can be made to be the same size automatically.

To make two TableControl blocks the same size:

1 Via Form Editor, select the first TableControl block. 2 Hold down <Ctrl> and click the other TableControl block. 3 Click the appropriate button on the toolbar: Make Same Height Matches the vertical size of the TableControl block with the size of the first selected TableControl block. Make Same Width Matches the horizontal size of the TableControl block with the size of the first TableControl block. Make Same Size Matches both the vertical and horizontal size of the TableControl block with the first selected TableControl block.

34.19 Assigning or Removing an Option for Multiple Fields

You can assign or remove an option for a group of fields simultaneously.

To assign or remove an option to multiple fields:

1 Select the required fields, by clicking each field while holding down the <Ctrl> key. 2 Keep the <Ctrl> key held down, right-click and choose Properties. The Field in Form Options form is displayed:

34-31

34

What is the Presentation Undoing Modifications

3 Select the option you want and click either Assign or Remove. The option is assigned to or unassigned from the selected fields.

34.20 Undoing Modifications

Undoing One Step at a Time
You can undo the effect of the most recent action if that action is reversible.

To undo the most recent action: Click the Undo button.

If you change your mind, you can reverse the undo with the Redo button, as long as you have not performed any new editing actions.

Restoring the Form Definition

You can restore the modified form to the last saved version in the knowledgebase.

To restore the modified form: Right click the form and choose Restore.

Re-initializing the Form Definition

You can reset the form definition (or parts of it) to remove changes and take them back to the initial defaults.

To reset the form definition:

1 Right-click the form. From the Reset Form option, choose the type of reset you want. Following are the types of reset: All Resets the position of the form, blocks, fields, text lines and form actions according to the order in which they appear in the operation. The width and height of the fields are reset to their default values. The color of the objects and the font used are reset to their default values. All lines,

34-32

What is the Presentation Adding Meta Tags to eMerge Forms

frames or images that were added are removed. Any template information is also removed. Color Font Resets the color of the objects on the form to their default colors. Resets the font to the default font. Resets the background color to the default color.

Background Color Actions

Resets the form action buttons to their original position.

Position Resets the position according to one of the following possibilities: Whole Form The position of the form, blocks, fields, text lines and private buttons are reset according to the operation order. The width and height of the fields are reset to their default values. Field in Block All the fonts and fields in a selected block are reset according to the operation order. Tab Order

Resets the tab order according to:

The block numbers in the form. The order of the fields in the operation contained in each block. A TableControl block is one item in the tab order. A tab control in the form is ordered as the last block and is one item in the tab order. The tab order within each tab page is determined by the tab page form (i.e. the called form of the tab page).

34.21 Adding Meta Tags to eMerge Forms

Meta tags are used to provide structured metadata fora HTML pages. Meta tags can be used to specify page description, keywords and any other metadata not provided through the other head elements and attributes. Many search engines use this information when building their indices. Such tags must be placed as tags in the head section of an HTML or XHTML document. Meta tags can be added to eMerge forms.

To add meta tags to eMerge forms:

1 Define a filenamed meta.htmcontaining the needed meta tag. 2 Store the file according to how the meta tag is to be used: Meta tags that are used in multiple applications are stored in the <sapiens>\db\eObjects directory.

34-33

34

What is the Presentation Adding Meta Tags to eMerge Forms

Meta tags that are used with a specific database are stored in the <sapiens>\db\<catalogID><xx>\eObjects directory, where <catalogID><xx> is the identifier used to identify which directory and which files belong to a particular module.

34-34

Chapter 35 Data Forms

Data forms are used to enter data. The end user enters data into the forms you create.

35.1 Creating a Data Form

The following is the recommended order when creating a form. Each step is described in subsequent sections or chapters.

To create a new form:

1 Define a new form. Define a form for a concept design and choose a suitable form template. See "Defining a Data Form" on page 35-2. 2 Insert one or more blocks. Blocks are areas on a form that contain data fields. Blocks define which operation, program, or query is being used by the form. See "Defining a Block" on page 35-4.

3 Insert a tab control if needed. The tab control enables the display of a set of forms (i.e. called forms) as a set of tab pages within the same area of one data form. See "Defining a Tab Control" on page 35-21. 4 Insert any form actions. Form actions are used by the end user to initiate form-dependent actions (e.g. calling another form). See "Inserting an Action into a Data Form" on page 35-30. 5 Define any entry and/or exit commands. Define commands that affect the working environment for a form on accessing (i.e. entry) and on exiting a form (i.e. exit). See "Entry and Exit Commands for a Data Form" on page 35-32. 6 Customize the display type and presentation for the fields. The display types for a field determine how a field is displayed on a form for the end user. See "Field Display Types" on page 35-33, "Customizing Field Presentation" on page 35-40, "Changing Tab Order" on page 35-48, "Displaying Binary Large Objects" on page 35-50, and "Multilingual Forms" on page 35-54.

35-1

35

Data Forms Defining a Data Form

7 Display the form to evaluate how it looks so far. See "Evaluating Initial Form Display" on page 35-54. Further enhancing of the form (e.g. adding text, lines, rectangles, groupboxes, or images, changing colors) is done via Form Editor. See Chapter 34, What is the Presentation.

35.2 Defining a Data Form

To define a new data form via a concept:

1 Using Modeler, right-click the concept and choose ObjectConcept Design. The Concept: Design form for the concept is displayed:

2 Right-click the Design field and choose Forms to display the Constructor Forms form:

35-2

Data Forms Defining a Data Form

3 Enter the new form name in the Form field. This is the title that appears at the top of the form. If the concept is a root concept, then, under Parent, assign the NoDisplay option. In the Occ field, enter the number of rows of data that should be displayed on the form. 4 In the Template field, choose the number of a template from the dropdown listbox. See Chapter 43, Form Templates for details of how to create a new template. 5 Click Display to see the new form. 6 Click the Form Editor button. The form changes so that you can edit it and the Form Editor toolbars are displayed. Using Form Editor, you can begin to modify the display of the form; i.e. add blocks, a tab control, form actions, form enhancements, etc.

To define a new data form via the Presentation tab of Development Workbench:

1 Right-click the Forms node on the Presentation tab and choose New Data Form, the Data Form form is displayed:

2 Enter the new form number and name in the Form No. and Name fields. This is the title that appears at the top of the form.

35-3

35

Data Forms Defining a Block

3 In the Template field, choose the number of a template from the dropdown listbox. See Chapter 43, Form Templates for details of how to create a new template. 4 Click Display to see the new form. 5 Click the Form Editor button. The form changes so that you can edit it and the Form Editor toolbars are displayed. Using Form Editor, you can begin to modify the display of the form; i.e. add blocks, a tab control, form actions, form enhancements, etc.

35.3 Defining a Block

Blocks are areas on a form that contain data fields. Each block uses one of the following to retrieve or update data: Operation Query Program Once blocks have been added to a form, the fields within them do not need to remain together in one area of the form; the fields may be moved around independently. See "Moving Objects Around the Form" on page 34-13.

Inserting a Block

To insert a block:

1 Using Form Editor, click the Insert Block button on the toolbar. Click the left mouse button where you want the block to be on your form. The Block form is displayed:

35-4

Data Forms Defining a Block

2 In the Block No. field, define the block number that uniquely identifies the block in the form. Use block numbers in tens (e.g. 10, 20, 30...) to allow addition of others in the future.

3 Specify the Message Type: Operation, Program or Query that the block is
It is not necessary to specify Operation Code or Block Type at this point.

to contain. For each, there are two fields. The first is the number; the second is the name. 4 Specify the number of occurrences you need in the Occurrences field. The following values are available: -1 the maximum number possible that fits onto the form. 0 one occurrence. A positive value results in that number of occurrences being displayed.

35-5

35

Data Forms Defining a Block

5 Assign TitlesOn to place the field names above the fields rather than on the side of the fields. This is useful for multi-occurrence blocks. 6 Assign any other options required and click OK. The new block is displayed on the form. 7 Repeat Steps 1 to 6 if more than one block is needed in the form.

Copying a Block
The definition for a block can be copied to a new block. All properties of the block are copied, except any text defined for the block. The form being copied from and the one being copied to must be the same type (e.g. a data form).

To copy an existing block from a form to a new block (in the same form or another form):

1 Access the Form Definition form for the form. 2 Right-click in the Block No. field and choose Copy to. The Copy to Block/Node form is displayed:

3 In the New groupbox, enter the number for the new block and the number and name of the form to which the new block is copied. 4 Click Copy.

35-6

To copy an existing block from a form (the same form or another form) to a new block in the form:

1 Access the Form Definition form for the form.

Data Forms Modifying a Block

2 Right-click in the Block No. field and choose Copy from. The Copy from Block/Node form is displayed:

3 In the From groupbox, enter the number of the block to be copied and the number and name of the form from which the block is copied. 4 In the New groupbox, enter the number for the new block. 5 Click Copy.

35.4 Modifying a Block

Blocks can be displayed in one of several block types. You can edit the properties of any block. Using Form Editor, changes are done via the Block form (see "Accessing the Block Form via Form Editor" on page 35-13) and directly on the form.

35-7

35

Data Forms Modifying a Block

Block Types
InRow Each field name is displayed in the form row (i.e. occurrence) just before the field value (i.e. the title is in the row). The block is not assigned the TitlesOn option.

TitlesOn

Each field name is displayed in the row (i.e. occurrence) above the field values (i.e. the title is on the row). A TitlesOn block is usually a multioccurrence block. The block is assigned the TitlesOn option.
field name

field values

35-8

Data Forms Modifying a Block

TableControl

Data in a multi-occurrence block (assigned the TitlesOn option) can be displayed in a form via a TableControl block.

The end user of a TableControl block can:

Manipulate data (i.e. inserting, deleting, viewing, etc.) in a TableControl block via a popup menu, accessed by pressing <shift> while right-clicking the table. Enable copying or cutting all or part (e.g rows, columns, cells) of a TableControl block.

Selecting and copying (<Ctrl>+<C>) makes the data available for eMerge and places the data on Windows Clipboard. The data is copied with all hidden fields but without the column titles. Right-clicking in the TableControl block and choosing Export to Clipboard places the data on Windows Clipboard. The data is copied without the hidden fields but with the column titles.

Once the data is on the Clipboard, the data is available for use in applications outside of eMerge. The data is stored on the Clipboard as HTML text in the following format:
<table id="block_no"> <tr occid="occurrence_id"> <td nowrap id="column_sequence_no" sid="field_internal_id" sapid="field_id" width="size"
35-9

35

Data Forms Modifying a Block

> </td> .... <tr> .... </table> EDTedit control CHBcheckbox SELlistdrop ECMBeditdrop

type="EDT|CHB|SEL| ECMB" val="checkbox_value"

where type can be one of the following:

Adjust the width of the columns in a TableControl block. Sort according to columns in the table (ascending or descending). The sort can be a single-column or multi-column sort. Search the table or a cell within the table. Export the table to an Excel spreadsheet via the DOM extensions. Scroll via scroll bars (which are enabled when needed). Occurrences are saved in the eMerge Client context and used for local scrolling. The Occurrences Per Retrieval field controls the number of occurrences retrieved for each retrieval from Business Integrity Server (up to 999). The Next and Previous actions are used to request server paging. The NoFurtherRetrieval option specifies that no further retrieval is enabled; i.e. the Next and Previous actions are not enabled. The DataAccumulation option specifies that the data requested from Business Integrity Server is added to the data stored in the eMerge Client memoryinstead of replacing the stored data. Choose between modes of working within the table control:

Row Mode (Esc)The focus is on a row (i.e. an occurrence); thus, enabling copying, inserting, and deleting rows:

35-10

Data Forms Modifying a Block

Cell Mode (Insert)The focus is on a cell (i.e. a field); thus, enabling inserting, editing, copying, and deleting data in a particular cell:

DynamicDetails

All the dependents of a parent occurrence in a block assigned the TitlesOn option can be displayed in a dependent block. The dependents displayed in the dependent block change as a different parent occurrence is selected. The selected parent occurrence is indicated by the background color.

35-11

35

Data Forms Modifying a Block

The dependent block can, in turn, have its own dependent block that changes as a different parent occurrence is selected.

MultiLineEdit

Text data in a block assigned the TitlesOn option can be displayed as lines of text with a scroll bar on the right; i.e. as a MultiLineEdit block. Scrolling

35-12

Data Forms Modifying a Block

displays additional text lines. Sequence numbers are not displayed. As text is entered into the block, the text is automatically wrapped.

Accessing the Block Form via Form Editor

Using Form Editor, right-click the block you want to edit and choose Block Properties from the popup menu. The Block form is displayed:

35-13

35

Data Forms Modifying a Block

Displaying a Block as a Titleson Block

1 Using Form Editor, access the Block form. 2 Assign the TitlesOn option to the block.

Displaying a Block as a TableControl Block

1 Using Form Editor, access the Block form. 2 Assign the TitlesOn option to the block. 3 Select TableControl in the Block Type field. The block is displayed as a TableControl block. 4 Make any customizing you need to override the default formatting. See "Working with a TableControl Block" on page 35-17.

35-14

Data Forms Modifying a Block

Displaying a Block as a DynamicDetails Block

1 Access the FormDefinition form for the form. 2 In the Block tabpage, with the cursor in the parent block: 1. Assign the TitlesOn option and the DynamicDetails option. 2. Click the Fields button. The Fields in Block Form Definition form is displayed. 3. Ensure that the Common option is assigned to the parent key fields. 3 In the Block tabpage, with the cursor in the dependent block: 1. Click the Fields button. The Fields in Block Form Definition form is displayed. 2. Ensure that the Common option is assigned to the parent key fields.

Displaying a Block as a MultiLineEdit Block

There is a difference when displaying a MultiLineEdit block based on an operation defined for a document concept or one not defined for a document concept. For a block based on an operation defined for a document concept: 1 Using Form Editor, access the Block form. 2 Assign the TitlesOn option to the block. 3 Ensure that the Occurrences field is other than one or zero. 4 Select MultiLineEdit in the Block Type field. The block is displayed as a MultiLineEdit block. 5 If you do not want automatic wrapping within the MultiLineEdit block, assign the Multi Line Edit parameter in the Global Options section of eMerge Client Administration. If Multi Line Edit is assigned, \n is added for the presentation of each line so there is no automatic wrapping of text. For a block not based on an operation defined for a document concept: 1 Ensure the block is based on an operation for a dependent class. The dependent class must contain a numeric Key field (to be used as the set of sequence numbers) and a text field (i.e. a Character data type of any size). 2 Assign the InsertEqualChange and the MayChangeNothing options to the operation. 3 Assign the NoFreePosition option to the text field in the operation.
35-15

35

Data Forms Modifying a Block

4 Using Form Editor, access the Block form. 5 Assign the TitlesOn option to the block. 6 Ensure that the Occurrences field is other than one or zero. 7 Select MultiLineEdit in the Block Type field. The block is displayed as a MultiLineEdit block. 8 If you do not want automatic wrapping within the MultiLineEdit block, assign the Multi Line Edit parameter in the Global Options section of eMerge Client Administration. If Multi Line Edit is assigned, \n is added to each line so there is no automatic wrapping of text.

Displaying Occurrences in Horizontal Order

Occurrences in a block can be displayed in horizontal order instead of vertical order (the default). This enables the cursor to advance horizontally from one occurrence to the next one, in sequence.

To display occurrences in horizontal order:

1 Using Form Editor, access the Block form. 2 Ensure that the Occurrences field is other than one or zero. 3 Ensure that the value in the Occurrences in Line field is neither the default value nor zero.

4 Assign the TitlesOn option and the HorizontalOccurrences option to the block. Example: Without the HorizontalOccurrences option:
CHILD NO CHILD NAME BIRTH DATE _ ____ occurrence 1_____ __________ _ ____ occurrence 2_____ __________ _ ____ occurrence 3_____ __________ _ ____ occurrence 4_____ __________ _ ____ occurrence 5_____ __________ CHILD NO CHILD NAME BIRTH DATE _ ____ occurrence 6_____ __________ _ ____ occurrence 7_____ __________ _ ____ occurrence 8_____ __________ _ ____ occurrence 9_____ __________ _ ____ occurrence 10____ __________

With the HorizontalOccurrences option:

35-16

Data Forms Working with a TableControl Block

CHILD NO CHILD NAME BIRTH DATE _ ____ occurrence 1_____ __________ _ ____ occurrence 3_____ __________ _ ____ occurrence 5_____ __________ _ ____ occurrence 7_____ __________ _ ____ occurrence 9_____ __________

CHILD NO CHILD NAME BIRTH DATE _ ____ occurrence 2_____ __________ _ ____ occurrence 4_____ __________ _ ____ occurrence 6_____ __________ _ ____ occurrence 8_____ __________ _ ____ occurrence 10____ __________

35.5 Working with a TableControl Block

You can display data in a form via a TableControl block. Manipulating data (i.e. inserting, deleting, viewing, etc.) in a TableControl block by the end user is done via a popup menu, accessed by right-clicking the table. The width of the columns in a TableControl block can be adjusted by the end user. The table can be sorted according to columns in the table (ascending or descending) by the end user. The sort can be a singlecolumn or multi-column sort.

Modifying a TableControl Block

To modify a TableControl block:

1 Using Form Editor, right-click the TableControl block you want to modify. 2 Choose Properties. The Table Control Property form is displayed:

35-17

35

Data Forms Working with a TableControl Block

3 Make any needed changes via the set of nodes. General To modify properties that pertain to the entire table.

Columns To modify properties that pertain to a particular column in the TableControl block. To access a particular column, double-click the column within the nodes on the left in the Table Control Property form. Table Content To modify properties that pertain to the contents of the TableControl block. Formatting To modify properties that pertain to the TableControl blocks formatting. The properties defined here override the properties defined within the form template default formatting or the form default formatting. Or 1 Using Form Editor, right-click the TableControl block you want to modify. 2 Choose Set Edit Table Ctrl. The TableControl block is selected.

35-18

Data Forms Working with a TableControl Block

3 Select any parts of the TableControl block that you want and right-click. 4 Choose the needed menu option.

Shrinkwrapping a TableControl Block

You can adjust the size of a TableControl block automatically to be equal to the total width of the columns.

To shrinkwrap a TableControl block:

1 Using Form Editor, right-click the TableControl block you want.

2 Choose Shrinkwrap. The size of the TableControl block is adjusted to be equal to the total width of the columns.

Defining a Popup Menu for Rows of a TableControl Block

A popup menu can be defined for rows of a TableControl block.

To define a popup menu for rows of a TableControl block:

1 Using Form Editor, right-click the TableControl block you want to modify. 2 Choose Properties. The Table Control Property form is displayed. 3 Via the General tab, enter an existing popup menu number in the Row Popup Menu field or click the New button to define a new popup menu.

Long Character Fields in a TableControl Block

Long character fields can be assigned the MultiLineEdit option (via the GUI tab page of the Field Definition form) to enable presenting long data fields

35-19

35

Data Forms Working with a TableControl Block

with automatic wrapping and scrolling. These fields can be used in a TableControl block.

Improving Response Time for a TableControl Block

Improve the response time when retrieving data for a TableControl block via the following:

Assign one of the following options to an action via the Action Definition form:

EchoAllOnReturnRetrieves and displays on the form all the occurrences (of all operations) which were retrieved and displayed on the current form before the action was invoked. This can take

35-20

Data Forms Defining a Tab Control

a lot of time since one operation is sent for each occurrence that is displayed.

EchoCurrentOnReturnRetrieves only the cursor where the cursor is. Since only one operation is sent, this takes very little time. RefreshOnReturnRetrieves and displays the data as if the first occurrence of the form is retrieved with an Edit operation code. Since only one operation is sent, this takes very little time.

Define the Max. Table Capacity field to limit the total number of occurrences that can be retrieved for a TableControl block. Define the field via the Table Control Properties form.

35.6 Defining a Tab Control

A tab control within a data form enables the display of a set of forms (i.e. called forms) as a set of tab pages within the same area of one data form.

tab control tab tab page

tab page form (called form)

Each tab page is assigned to a particular tab page form (i.e. its called form). The called form can contain more than one block. Each tab page has a tab that can contain a label and/or an icon. The set of tab pages within a tab control can be formatted as a whole or each tab page can have its own formatting; e.g. color, font. All called forms of one tab control are included in one unit of work. To decrease time for the form containing the tab control to be "painted" on the computer screen, only the active tabpage is "painted"
35-21

35

Data Forms Defining a Tab Control

when the form is first displayed. The other tabpages are painted as needed; i.e. as they are accessed. If there is a need to have all the tabpages of the form painted on the computer screen when the form is displayed, assign the PaintAllTabPages option via the property sheet of the form definition for the form. The PaintAllTabPages option determines that all the tabpages are painted when the form is first displayed.

Inserting a Tab Control

1 Using Form Editor, click the Insert TabControl button on the toolbar. Click the left mouse button where you want the tab control to be on your form and drag the pointer to insert the tab control. The New Tab Control form is displayed:

35-22

Data Forms Defining a Tab Control

2 In the Tab Control ID field, define a tab control number that uniquely identifies the tab control within the form. 3 In the Tab Page ID field, define a tab page number that uniquely identifies this tab page within the tab control. Use numbers in multiples of ten (e.g. 10, 20, 30...) to allow addition of others in the future. 4 Each tab page has a tab that can contain a label and/or an icon.

In the Tab Icon field, click the ellipsis button () to choose an icon for the tab. The file must be in the <sapiens>\DB\<databaseID>\eobjects or <sapiens>\DB\eobjects directory where <sapiens> is the root directory where eMerge Client files are stored <databaseID> is the two-character database ID used to identify which directory and which files belong to a particular database.

In the Tab Label category, enter the label for the tab.

5 If the tab page form has already been defined: Enter the form number in the No. field or select the form name in the Name field to assign the tab page form to this particular tab pagei.e. its called form. Go on to Step 7.

Note that only forms defined as tab page forms can be assigned to a tab page.

Or If the tab page form has not already been defined: Click the New button. The Tab Page Form form is displayed:

35-23

35

Data Forms Defining a Tab Control

6 Define the tab page form: 1. Enter the form number in the Form No. field and the form name in the Name field, and click Apply. 2. Define the tab page form: Use the relevant tab pages in the Tab Page Form form to define blocks, actions, entry and exit commands, components, and events for the tab page form. Note the tab page form can contain more than one block. 3. Click OK to return to the New Tab Control form. 7 Click OK. A tab control with one tab page form is displayed within the form.

Adding a Tab Page to a Tab Control

1 Using Form Editor, right-click the tab control and choose Add Tab. The Tab Control Properties tree compound form is displayed with the New Tab Page in Tab Control form displayed:

35-24

Data Forms Defining a Tab Control

2 In the Tab Page ID field, define a tab page number that uniquely identifies this tab page within the tab control. Use numbers in multiples of ten (e.g. 10, 20, 30...) to allow addition of others in the future. 3 Each tab page has a tab that can contain a label and/or an icon.

In the Tab Icon field, click the ellipsis button () to choose an icon for the tab. The file must be in the <sapiens>\DB\<databaseID>\eobjects or <sapiens>\DB\eobjects directory where <sapiens> is the root directory where eMerge Client files are stored <databaseID> is the two-character database ID used to identify which directory and which files belong to a particular database.

In the Tab Label category, enter the label for the tab.

4 If the tab page form has already been defined: Enter the form number in the No. field or select the form name in the Name field to assign the tab page form to this particular tab pagei.e. its called form. Go on to Step 6.

Note that only forms defined as tab page forms can be assigned to a tab page.

Or
35-25

35

Data Forms Defining a Tab Control

If the tab page form has not already been defined: Click the New button. The Tab Page Form form is displayed. 5 Define the tab page form: 1. Enter the form number in the Form No. field and the form name in the Name field, and click Apply. 2. Define the tab page form: Use the relevant tab pages in the Tab Page Form form to define blocks, actions, entry and exit commands, components, and events for the tab page form. Note the tab page form can contain more than one block. 3. Click OK to return to the New Tab Control form. 6 Assign Disabled or Hidden to the tab page if needed. Disabled Disables the tab page within the tab control. That is, the tab of the tab page is visible, but not accessible for the initial display of the tab control in the form. The tab page can be accessed via the DOM API extensions. Hidden Hides the tab page within the tab control. That is, the tab page and its tab are not only not accessible, they are not even visible for the initial display of the tab control in the form. The tab page can be made visible via the DOM API extensions. 7 Click OK or Apply. The tab page form is added to the tab control.

Formatting the Tab Control as a Whole

1 Using Form Editor, right-click the tab control and choose Properties. The Tab Control Properties tree compound form is displayed. 2 In the tree form, double-click Formatting. The Tab Control Properties tree compound form is displayed with the Formatting form displayed:

35-26

Data Forms Defining a Tab Control

3 Make any needed formatting to the tab control via the Formatting form.

Modifying a Tab Page Form within a Tab Control

1 Using Form Editor, right-click the tab control and choose Set Edit Tab Ctrl. 2 Click the tab of the tab page form you want to modify. The tab page becomes the active tab page. 3 Right-click the tab page and choose Form Editor for Called Form. The form changes so that you can edit it and the Form Editor toolbars are displayed. 4 Make any needed modifications to display of the form. 5 Click Save to save all changes to the tab page form. 6 Right-click within the tab page form and choose Return to Tab Control.

Converting a Existing Data Form to a Tab Page Form

An existing data form can be converted to a tab page form.

35-27

35

Data Forms Defining a Tab Control

Note that an existing data form cannot be converted to a tab page if any of the following apply:

Error overrides are defined for the data form. The Group option is assigned to the data form. The data form is used as a detail form or as a select form. The data form is used as an output form for a query or a program.

To convert an existing data form to a tab page form:

1 Access the definition form for the form you wish to convert:

2 Choose Tab Page from the Form Type field. 3 Click Apply to save the changes. The form is now a tab page form available for use via a tab control.

Copying an Existing Data Form to a New Tab Page Form

An existing data form can be copied to a new tab page form. Note that an existing data form cannot be copied to a new tab page if any of the following apply:

Error overrides are defined for the data form. The Group option is assigned to the data form.

35-28

To copy an existing data form to a new tab page form:

1 Access the definition form of the form you wish to copy.

Data Forms Defining a Tab Control

2 Right-click the Form No. field and choose Copy. The Copy/Form/Menu/Tree/Template form is displayed:

3 Enter a form number in the Form No. field of the To groupbox. 4 Enter a form name in the Form Name field of the To groupbox. 5 Choose Tab Page from the Type field. 6 Click Copy to return to the form definition form. The new form can be used as a tab page form for a tab control.

Copying an Existing Form to a Tab Page Form of a Tab Control

1 Using Form Editor, right-click the tab control and choose Add Tab. The Tab Control Properties tree compound form is displayed with the New Tab Page in Tab Control form displayed: 2 In the Tab Page ID field, define a tab page number that uniquely identifies this tab page within the tab control. Use numbers in tens (e.g. 10, 20, 30...) to allow addition of others in the future. 3 Each tab page has a tab that can contain a label and/or an icon.

In the Tab Icon field, click the ellipsis button () to choose an icon for the tab. In the Display Text category, enter the label for the tab.
35-29

35

Data Forms Inserting an Action into a Data Form

4 Click the New button. The Tab Page Form form is displayed. 5 Define the tab page form: Enter the form number in the Form No. field and the form name in the Name field, and click Apply. 6 Right-click in an empty Block field and choose Copy from. The Copy from Block/Node form is displayed:

7 Enter the form number or select the form name in the Form field and select the needed bock in the From category. 8 Enter the block number for the new tab page form in the To category. Note the form number and form name are already entered in the To category. 9 Click Copy to return to the Tab Page Form form. 10 Repeat Steps 6 through 9 for any other blocks that you want to copy from an existing form. 11 Use the relevant tab pages to define any other blocks, actions, entry and exit commands, components and events for the tab page form. Note the tab page form can contain more than one block. 12 Click OK to return to the Tab Control Properties form.

35.7 Inserting an Action into a Data Form

1 Using Form Editor, click the Insert Action button on the toolbar. 2 Click the left mouse button where you want the action to be on your form and drag to create the size of button you want.

35-30

Data Forms Inserting an Action into a Data Form

3 Click the Save button. 4 Right-click the new action and choose Properties. The Action Definition form is displayed:

5 Enter the name you want for the action button in the Name field. The name can be used to invoke the action from the Insert Command box on the toolbar. 6 In the Displayed Names category, enter the name you want to appear on the button (if it is different from the name entered in the Names category). 7 In the Activity Invoked subgroupbox, enter the action you want when the button is clicked: Called Form/Block BLP Command
35-31

35

Data Forms Entry and Exit Commands for a Data Form

8 Click OK to close the form. The button is displayed on the form. The display of eMerge form actions is determined by the following:

The form actions are displayed as buttons unless they are assigned the HyperText option. If a form action has been assigned the HyperImage option and an image has been added to the button (see "Adding Images to a Form" on page 34-23), the form action is displayed as a button with an image on it.

See "Form Actions" on page 39-1.

35.8 Entry and Exit Commands for a Data Form

You can define commands that affect the working environment for a form on accessing (i.e. entry) and on exiting a form (i.e. exit). The entry and exit commands specified for a form override any initial commands specified for a user or for a user's world. By default, the commands specified as entry commands are inherited by all called forms. The exit commands are activated when leaving the form where they are defined. Ensure that the exit commands, which are activated on leaving the form, complement the entry commands, which are activated on accessing the form. 1 Access the Form Definition form for the form. 2 Activate the Entry/Exit Commands tab page:

35-32

Data Forms Field Display Types

3 Specify the entry and exit commands you want. Example: Enter GROUP ON in the Entry Commands field and GROUP OFF in the Exit Commands field.

Execution commands (e.g. COMPILE) and the LANGUAGE command must not be defined.

35.9 Field Display Types

Default Display for a Field
The display types for a field determine how a field is displayed on a form for the end user (as opposed to the data type which is how the field is stored in the knowledgebase). The following defaults are used for the display of data entry forms: Field Without Possible Values

The field is displayed as an editdrop with the automatically generated multiple occurrence form defined as the control select form: If the field is defined via an entity in Modeler and is a Key or Name field If the Key field is assigned the Entity option and is the Key or Name field
35-33

35

Data Forms Field Display Types

For a root entity (or root class) the Key and Name fields should be assigned the NoSelection and NoDetailForm options on the form-level.

If the field is not one of the above, it is displayed as an editbox:

Field with a Range of Possible Values Field with Distinct Possible Values

The field is displayed as an editbox. The user can click the Select Value button to display the range of values. The field is initially displayed as a listdrop. Clicking the field or the arrow next to the field lists the meanings (or if no meanings have been defined, the possible values) defined for the field. If there are more values than can fit in the listdrop, a scroll bar is available. The list of values is displayed above or below the field, depending on where there is more space. The field is displayed as a multi-selection listbox. For a hexadecimal field with distinct possible values, the choices come from the values in the Meaning field on the Domain Definition form. Values can be assigned via a calendar dialog box. The calendar dialog box is displayed when the user double-clicks the field, clicks the Select Value button with the insertion point in the field, or chooses Select on the popup menu for the field.

Hexadecimal Field Field Having a Date Data Type

Available Display Types

The following display types are available:

35-34

Data Forms Field Display Types

EditBox

The default display type. A rectangle into which you type information. When the editbox is clicked, an insertion point indicates where the typed characters appear.

Double-clicking selects the value in the editbox. Editbox can be used for any field, even a field with a hexadecimal data type or a field with distinct possible values. If there are distinct possible values, they are displayed when double-clicking the field. ListDrop Initially, a box appears with the current selection displayed.

Clicking the arrow at the right of the box displays the list of choices. If the number of choices is greater than can fit into the drop-down list box, a scroll bar is available. ListDrop can only be used for a field (other than hexadecimal) with distinct possible values or a field with a control select form defined. The output length of the ListDrop box is determined dynamically by the length of the longest possible value. If you are using a proportional font with long possible values, you may have to widen the ListDrop box via Form Editor to display the entire possible value. EditDrop Initially, a box appears with the current selection displayed. You can type one of the possible values into the text box. Clicking the arrow at the right of the box displays the list of choices. If the number of choices is greater than can fit into the drop-down list box, a scroll bar is available:

35-35

35

Data Forms Field Display Types

The number of choices displayed is dependent on the amount of space on the form below the drop-down list box. If the drop-down list box is at the bottom of the form, you can show more choices by dragging the window frame to make the window bigger. When the drop-down list box is open:

The up arrow and down arrow move through the list of choices. Typing into the text box brings you to the relevant part of the list of choices.

EditDrop can only be used for a field (other than hexadecimal) with distinct possible values or a field with a control select form defined. ListBox A column of available choices is always displayed. If there are more choices than can fit in the list box, a scroll bar is available.

ListBox can only be used for a field (other than hexadecimal) with distinct possible values or a field with a control select form defined. OptionButton A list of options. Only one option can be chosen. Clicking an option button selects the option. Option buttons are used to present a list of mutually exclusive options.

OptionButton can only be used for a field (other than hexadecimal) with distinct possible values. Up to 200 items can be listed in one form.

35-36

Data Forms Field Display Types

Checkbox

A list of options. One or more can be selected.

CheckBox can only be used to display:

One or many possible values with checkboxes that can be selected. In this case the field data type must be Hexadecimal. A checkbox for just one defined possible value; i.e. the field either has the defined possible value or it does not. If the check box is off, the value is not selected; if the check box is on, the value is selected. A checkbox for just two defined possible values; i.e. the field either has one or the other of the two possible values. If the check box is off, the first value is selected; if the check box is on, the second value is selected.

To display the possible value meanings together with CheckBox display type, TitlesOn must not be assigned. (For multioccurrence fields, TitlesOn is assigned by default and must be unassigned to display possible value meanings).

ViewBox

If you have more than one hexadecimal field defined in the form and you have not assigned HexaAlone to the field, the hexadecimal fields are merged. Thus, even if you have entered a different display type for each hexadecimal field, the display type of the first hexadecimal field is the only one used.

Used only for a view-only field where the field remains constant the whole time the form is displayed. The use of Viewbox (instead of Editbox) results in shorter display times. The Protected option is automatically assigned when you use the ViewBox display type, and must not be unassigned. If you need tab order or distinct possible values functionality for the field, or if you are using any JavaScript-based components or events, use the display type Editbox and not ViewBox. A field assigned the ViewBox option cannot be accessed via DOM.

35-37

35

Data Forms Field Display Types

Modifying the Display Type

The display type can be modified on the following levels:

Field level: Where the definition of a field is held for the whole knowledgebase, so that the change applies wherever the field is used. Field in block level: In a particular block on a particular form only.

To modify the display type for a field in a block (i.e. in a particular form):

1 Using Form Editor, double-click the field you wish to change. If the field is in a multi-occurrence block, any other occurrences of that field are also highlighted. The Field in Block form is displayed:

2 Select the display type you want (instead of the default type) from the Display Type (Display category) field.

To modify the display type for a field (so that the change applies wherever the field is used):

1 Access the Field Definition form for the field.

35-38

Data Forms Field Display Types

2 Activate the GUI tab page:

3 In the Display Type category, select the display type you want (instead of the default type).

Select Value with Distinct Possible Values

When the user clicks Select Value on a field with distinct possible values, the results depend on the display type of the field:

If the display type is Editbox, the Possible Values dialog box is displayed, with the list of possible values, i.e. what was entered in the Low Value field for each value If the display type is one of the following, the list of meanings is shown as a list below the field.

ListDrop EditDrop ListBox

35-39

35

Data Forms Customizing Field Presentation

If only low values have been defined (no meanings), then they are shown in the list.

If the display type is one of the following, Select Value has no effect.

OptionButton CheckBox

35.10 Customizing Field Presentation

The definition of a field is normally set when the block is added to the form according to the general definitions it already has in the knowledgebase. However, you may want to customize the definition for a particular form.

To customize a field:

1 Using Form Editor, double-click the field you wish to change. If the field is in a multi-occurrence block, any other occurrences of that field are also highlighted. The Field in Block form is displayed. 2 Make any needed customizing to the presentation of the field (in the block) in the form.

Displaying A Common Value Only Once

Often the same field value is used to identify a number of operation occurrences when the field is in the path of the two occurrences. You can specify that the value be displayed only once.

To display a common value only once: Assign the Common option to the field. Example: The Passport No field is repeated in each occurrence in the first form, when the Common option is not assigned. In the second form, when the Common option is assigned, the field appears once, at the top of the form, and does not need to be entered for each new occurrence:

Without the Common option

35-40

Data Forms Customizing Field Presentation

With the Common Option

Displaying a Different Name

Usually, the field name that is displayed for a field is the field name defined in the concept. However, the displayed name for a field (i.e. the title) can be changed: on the operation level on the form level

for a particular field name for all visible fields in the form

To display a different name for a field in a form:

1 Using Form Editor, double-click the field name. The Displayed Names form is displayed:

35-41

35

Data Forms Customizing Field Presentation

2 Type the name that you want to appear on the form in the Displayed Name textbox.

To view or modify the displayed names of all the visible fields on a form:

1 Using Form Editor, right-click the form and choose Displayed Names. The Field Displayed Names form is displayed.

2 View, modify or add a displayed name in the Displayed Name textbox for any needed field. If the Titleson option is assigned for the block, eMerge automatically breaks long field names over more than one line (the break occurs at space characters between words in the field name). Use the following special characters to control the line break: Slash (/) Example: A slash breaks a string of characters forcing a line break. A field is called DefaultSubject

To break the string, type Default/Subject in the Displayed Names field to split the name more clearly as: Default Subject

35-42

Data Forms Customizing Field Presentation

at sign (@) The "at" sign represents a hard space, ensuring that a line break does not occur. Example: A field is called Start Employment If you know there is space on the form for the whole name on one line, you can enter it as Start@Employment. This prevents the system from breaking up the name (at the space character): Start Employment

Displaying Field Names with Titlecase

You can change the field names in a form to titlecase simultaneously. uppercase

titlecase

To display field names in titlecase:

1 Using Form Editor, right-click the form and choose Properties. The Form Definition form is displayed. 2 Assign TitleCase (Presentation category). The fields are displayed in titlecase.

Unassigning TitleCase does not effect fields already displayed in titlecase. However, any new fields defined for the form are displayed in uppercase.

Preventing Access To a Field

You can protect a field so that it appears on the form, but the user cannot access the value to change it in any way.

35-43

35

Data Forms Customizing Field Presentation

For details about preventing access to a field in every operation see "Stopping User Access to a Field" on page 33-11.

To protect a field in a particular form:

1 Using Form Editor, double-click the field you wish to change. The Field in Block form is displayed. 2 Assign ProtectEnabled (Presentation category) to the field.

Hiding a Field
You can hide a field that is defined in an operation so that it is not displayed in a particular block that uses this operation. The same operation can be used in other blocks in other forms where the field is displayed.

To hide the display of the field name and/or field value:

1 Using Form Editor, double-click the field. The Field In Block form is displayed.

2 To hide only the field name, assign NoName (Presentation category) to the field and click OK. 3 To hide only the field value, assign the Invisible (Values Presentation category) to the field and click OK. 4 To hide both the field name and value, assign Ignore (Presentation category) to the field and click OK. 5 To see a list of fields assigned Ignore, using Form Editor, right-click the form and choose Ignored Fields. The Ignored Fields form is displayed:

35-44

Data Forms Customizing Field Presentation

6 To allow a field to be displayed again, uncheck the check mark against it in the Ignore column and click OK.

Making a Field into a Password Field

You can hide a field value so that it is displayed as asterisks (i.e. ***).

To define a password field:

1 Using Form Editor, double-click the field. The Field In Block form is displayed.

2 Assign the Password (Values Presentation category) to the field.

35-45

35

Data Forms Customizing Field Presentation

Displaying Possible Values with OptionButton and CheckBox Display Types

You can customize how possible values are displayed on a form for display types OptionButton and Checkbox. You can:

display all possible values in only one column display all possible values in only one row display a specific number of possible values per row display a specific number of possible values per column

To display the possible value meanings together with CheckBox display type, TitlesOn must not be assigned. (For multioccurrence fields, TitlesOn is assigned by default and must be unassigned to display possible value meanings).

To display all the possible values in one column:

1 Using Form Editor, double-click the field you wish to change. The Field in Block form is displayed. 2 Leave No. of Values (Display category) empty or enter 0 or 1.
Do not assign ByColumn (Values Presentation category) to the field.

Example: Seven possible values are defined for a hexadecimal field. The display type is CheckBox. The No of Values (Display category) field value is 0 and ByColumn (Values Presentation category) is not assigned to the field:

To display all possible values in one row:

1 Using Form Editor, double-click the field you wish to change. The Field in Block form is displayed. 2 Leave No. of Values (Display category) empty or enter 0 or 1. 3 Assign ByColumn (Values Presentation category) to the field. Example: Seven possible values are defined for a hexadecimal field. The display type is CheckBox. The No of Values (Display category) field value is 1 and ByColumn (Values Presentation category) is assigned to the field:

35-46

Data Forms Customizing Field Presentation

To display a specific number of possible values per row:

1 Using Form Editor, double-click the field you wish to change. The Field in Block form is displayed. 2 In No. of Values (Display category), enter the number of values you want to display in a row.

Do not assign ByColumn (Values Presentation category) to the field.

Example: Seven possible values are defined for a hexadecimal field. The display type is CheckBox. The No. of Values (Display category) field value is 3 and ByColumn (Values Presentation category) is not assigned to the field:

To display a specific number of possible values per column:

1 Using Form Editor, double-click the field you wish to change. The Field in Block form is displayed. 2 In No. of Values (Display category), enter the number of values you want to display in a column.

3 Assign ByColumn (Values Presentation category) to the field. Example: Seven possible values are defined for a hexadecimal field. The display type is CheckBox. The No. of Values (Display category) field value is 3 and ByColumn (Values Presentation category) is assigned to the field:

Removing the Frame Around the Option Button Display Type

When two or more possible values are defined for a field and the OptionButton display type is used for the field, the options are displayed on the form grouped vertically together in a frame. Using Form Editor, the option buttons can be moved as a group. To be able to move an

35-47

35

Data Forms Changing Tab Order

individual option button, the frame around the option buttons must be removed.

To remove the frame around a set of option buttons:

1 Using Form Editor, double-click the field. The Field In Block form is displayed. The options buttons can now each be moved and located where required in the form:

2 Assign OptButnNoFrame (Values Presentation category) to the field.

35.11 Changing Tab Order

When an enduser opens a form and tabs through the form (i.e. moves from one field to another using the <tab>), there is a predefined order tab orderfor that movement. <Shift>+<tab> moves from one field to the other in reverse order.

35-48

Data Forms Changing Tab Order

When a form is first created (i.e. no specific tab order has been defined for any fields in the form) or if the tab order is reset, the tab order is ordered according to:

The block numbers in the form. The order of the fields in the operation contained in each block. A TableControl block is one item in the tab order. A tab control in the form is ordered as the last block and is one item in the tab order. The tab order within each tab page is determined by the tab page form (i.e. the called form of the tab page).

The tab order of a form can be changed to any order that is needed.

To change the tab order:

1 Click the Tab Order button. Each field on the form is displayed with a tab order box beside it. The box contains a sequence number which is the fields position in the current tab order:

Note that some boxes are yellow and others turquoise. The yellow boxes are those which may be changed. The turquoise are numbers of repeated occurrences and change when the first occurrence is changed. 2 Click each tab order box in turn in the order that you need. The sequence number changes when you click the tab order boxstarting from 1. The rest of the sequence numbers change appropriately. 3 When you have clicked all the fields on the form, click the Tab Order button again to finish.

An appropriate message is issued when an attempt is made to use Form Editor for a form which has a tab order that is incompletely defined. The message enables the developer to complete the definition of the tab order, reset the tab order, or to leave the tab order incompletely defined. The tab order can be reset by right-clicking the form and choosing Reset > Tab Order.

35-49

35

Data Forms Displaying Binary Large Objects

35.12 Displaying Binary Large Objects

You can display binary large objects (BLOBs) as part of the data displayed on an eMerge form. The formats supported depend on the web browser used to access the application. The form can contain:

A view of the BLOB and the reference (i.e. path) to the BLOB. See "Adding a View of a BLOB" on page 35-50. For a multi-occurrence form, the reference is given for each occurrence, but the view is seen in a common field. See "A Common View of a BLOB in a Multi-occurrence Form" on page 35-52.

For any form where the view and the reference are both displayed in the form, save storage space by defining an empty view field and adding it to an operation. See "Saving Storage Space" on page 35-53.

Adding a View of a BLOB

1 Add two fields to your concepta BLOB view field for the view of the BLOB and a BLOB reference field for the reference for the BLOB. Each field should have the Character data type and a size up to 78, but not smaller than the length of the path. Mapping the path might be a solution for very long paths. 2 Using Form Editor, right-click the BLOB view field and choose Properties. The Field in Block form is displayed. 3 Set the Display Type (Display category) to Image. Note the field number and click OK. 4 In the same way, right-click the BLOB reference field and display the he Field in Block form for this field. 5 In View Field (Behavior category), enter the field number of the BLOB view field. Click OK and exit Form Editor to redisplay the form. 6 Type the path for the image you want to display in the reference field and press <Enter>. The image is displayed in the BLOB view field.

35-50

Data Forms Displaying Binary Large Objects

Example: PICREF is the BLOB reference field and PICVIEW is the BLOB view field.

7 Using Form Editor, adjust the size and position of the BLOB view field to allow for the size of your pictures.

Hiding the BLOB Reference Field

If you do not want the end user to see the reference, then you may set the BLOB reference field to be hidden in the form by assigning Ignore (Presentation category) via the Field in Block form.

35-51

35

Data Forms Displaying Binary Large Objects

A Common View of a BLOB in a Multi-occurrence Form

When viewing BLOBs in a multi-occurrence form, the view should be in a common position for all occurrences.

1 Add a BLOB view field and a BLOB reference field to the concept and connect them as described for a single occurrence form in "Adding a View of a BLOB" on page 35-50. 2 Assign Common (Presentation category) to the BLOB view field. 3 Display the form. 4 Using Form Editor, adjust the size and position of the BLOB view field for the BLOB to your liking.

35-52

Data Forms Displaying Binary Large Objects

5 When the user clicks any field in an occurrence, the relevant BLOB is displayed in the same location for each occurrence:

Saving Storage Space

Rather than adding the BLOB view field to the concept, it may be added to the operation that displays the block. Use this procedure when saving storage space is important to you. 1 On the Data tab, right-click the Fields node and choose Insert Field. 2 Define a field to be the BLOB view field. The field should have the Character data type and a size up to 78, but not smaller than the length of the path. Note the number of the BLOB view field. 3 Add a BLOB reference field for the BLOB to your concept. The field should have the Character data type and a size between 50 to 78. Mapping the path might be a solution for very long paths. 1 Using Form Editor, double-click the BLOB reference field. The Field In Block form is displayed. 2 Enter the field number of your BLOB view field in View Field (Behavior category) and click OK. 3 Right-click the form and choose Properties. The Form Definition form is displayed.

35-53

35

Data Forms Multilingual Forms

4 Right-click in the Operation field for the desired block occurrence and choose Detail. The Operation Definition form is displayed. 5 Add the BLOB view field to the operation. 6 If the form is multi-occurrence, right-click in the BLOB view field and assign Header (Presentation category) to the new field. 7 Click OK to save and return to the form. 8 Adjust the size and position of the BLOB view field to your liking.

35.13 Multilingual Forms

eMerge includes the capability to tailor the same application for use in more than one language. Different end users can work with an application, each end user seeing forms and producing reports in a different language. For details see Chapter 62, Applications with More than One Language.

35.14 Evaluating Initial Form Display

The final step in creating a form is to look at the initial form display that has been created and evaluate its clarity and ease of use. Plan any improvements to the layout, user friendliness and completeness of the form. Since more than one form can be displayed simultaneously within the work pane, it is often preferable to break up data entry forms with more than one block into separate forms. As part of the flow design, consider whether or not to do this. When you are planning changes for a particular form, you must also consider whether these changes apply to other forms. You can change the way in which the data is presented to the user at different levels: Field in block level: In a particular block on a particular form only. See "Customizing Field Presentation" on page 35-40. Operation level: In an operation, so that the change applies whenever that operation is invoked by any block. Field level: Where the definition of a field is held for the whole knowledgebase, so that the change applies wherever the field is used.

35-54

Possible values for a field may only be defined at this level via a domain.

Data Forms Example of a Customized Single Occurrence Data Form

Example: Assigning the Quantity option to a field on the concept level adds the appropriate commas or periods to separate the thousands in a numeric field in every form where the field appears. Example: Usually, the name that is displayed for a field is the name defined in the Concept Fields form. The name can be changed for all forms invoking a particular operation.

35.15 Example of a Customized Single Occurrence Data Form

Initial Display with no Template
This is an initial display with no template defined for a data form:

Modified Display
This is a modified display of the same data form:

35-55

35

Data Forms Example of a Customized Multioccurrence Form

The following features have been incorporated into the modified form:

Employee Type is a set of option buttons; only one choice can be selected. Benefits is a set of check boxes; as many benefits as are appropriate can be chosen. Married is a check box; it is either selected or not. The other fields are editboxes. The field names have been aligned right. The entire block has a frame that makes it appear to jut out from the form. A frame around some of the fields makes those fields appear to jut out. The order in which the fields are displayed has been rearranged. The field names and field values have been moved closer together.

35.16 Example of a Customized Multioccurrence Form

The following forms show a multioccurrence form with a parent block and a dependent block:

Initial Display

35-56

Data Forms Example of a Customized Multioccurrence Form

Modified Display

In addition to the changes of the type of display for some of the fields, the following have been incorporated into the modified form:

Department is a drop-down listdrop. The possible choices are displayed when the arrow is clicked. The two blocks have been rearranged so that they are side by side. The two blocks each have a frame that makes the block appear to jut out from the form. Titles have been added to each block. The fields and field names in the Employee Details block are aligned differently. The color of the foreground and background have been changed so that they are not the same. The field names for Benefits and Employee Type have been repositioned.

35-57

35

Data Forms Example of a Customized Multioccurrence Form

35-58

Chapter 36 Menu Forms

A menu is a list of options presented to the user. By selecting one of these options the user navigates through the application or executes commands. One of two possible actions can be performed when the user selects a menu option:

If you specify a form number, that form is displayed. The called form can be either a form, a flow or another menu. If you specify a BLP command, the command is issued.

You cannot specify both a form and a command for the same menu option. There are two types of menu forms:

menu popup menu

36.1 Defining a Menu

To define a menu you must define the menu identifier (the name and number that uniquely identify the menu), the general menu characteristics, and the options that make up the menu.

36-1

36

Menu Forms Defining a Menu

To define a menu:

1 From the Presentation tab, right-click the Forms node and choose the New Menu Form option. The Menu form is displayed:

2 Enter the form number. Enter a name for the form in the Name field. The name can be up to 16 characters, consisting of letters, digits, blanks and any of these special characters: - _ ' " . and #. Assign any relevant options.

The GUI option (Presentation category)is assigned automatically to any menu that is generated via the Menu form.

3 Enter the menu options. Each menu option consists of the following parts:

36-2

Menu Forms Customizing Menu Forms

No: The number of the menu option. This determines the order in which they are displayed. You can overwrite these numbers (e.g. if you want increments of ten) by typing the number you want over the displayed number. Called Form: The number of the form to be called when the menu option is chosen. Displayed Text: A string that explains the menu option. The user sees a bullet followed by this text. If no displayed text is defined for a menu option, then the name of the form or the BLP command will be displayed in its place. BLP Command: The name of the command to be issued when the menu option is chosen. 4 Click Apply to create the new menu. 5 Test the menu by clicking the Display button.

36.2 Customizing Menu Forms

Using Form Editor, you can customize menus to your exact specification. The customizations you can do via Form Editor include:

Performing the same editing functions as for a data form Changing the displayed text for a menu option Adding text anywhere on a menu:

Above the set of menu options (as a header) Below the set of menu options Above a specific menu option By the side of the options

To put text above or between options, a little manipulation is required. All the options after the required text position must be selected together and moved down the form to make space. Then the new text may be added using the Insert Text button.

Adding form objects, including images Moving the form objects around the form Changing the image used for the icon for a menu option Change the image by right-clicking the icon and choosing Image > Select. The Open a File dialog box enables selecting the needed image.

36-3

36

Menu Forms Including Data in a Menu via Menu Fields

Before changing the menu option icon, read "Adding Images to a Form" on page 34-23.

36.3 Including Data in a Menu via Menu Fields

You can include a field value as part of a menu option, which the user can update, to provide information to be used in the called form, or as a parameter in a BLP command. You can also include a field in the menu header, which applies to every option in the menu. Control select, client select and detail forms can be defined for menu fields. If the menu is displayed via i.way, field details are only displayed in a separate window, when the user selects the menu option. i.way menu items can accept text input. They can also display forms as a result of choosing that menu option. In this case, when you return to the menu from the displayed form via the quit button, the cursor returns to that menu item text field.

Adding a Field to Apply to One Menu Option

To add a field to apply to one menu option:

1 Using Form Editor, double click the menu option where you want to add a field. The Menu Option Definition form is displayed:

36-4

Menu Forms Including Data in a Menu via Menu Fields

2 Enter the number of the relevant field in the Field textbox. 3 Enter an initial value, if required. The value is displayed when the menu is accessed. Only the field value is displayed, not the field name. You can include the name of the field in the text that is displayed for the option.

Adding a Field to Apply to All Menu Options

To include a field that applies to all menu options:

1 Using Form Editor, right click the menu form and choose Properties. The following form is displayed:

2 Overwrite the number in the No. column, for one of the unused menu options, with a 0. Option 0 will appear at the top of the form. Enter any text you need to describe the field, under Displayed Text. 3 Access the Menu: Option Definition (10641) form and specify the field name and an Initial Value if necessary. Click OK. 4 Click OK in the other two forms to return to the edited form. The new field and any associated text is added at the top of the menu. It may be necessary at this stage to move other options down to correct the form layout. Example:

36-5

36

Menu Forms Defining a Menu with Only One Option

Employee number may be passed to whichever form is chosen. The skill level number can be entered before entering the skill form.

36.4 Defining a Menu with Only One Option

If you define a menu with only one option, on entry to the menu the option is automatically initiated. That is, the called form is accessed or the BLP command is executed.

36.5 Defining a Popup Menu for a Field in a Data Form

eMerge supports the following popup menus for a field in a data form:

system field popup menu user-defined field popup menu

System Field Popup Menu All fields that have a Select or Detail form (associated the field) are automatically given a system field popup menu containing Select and Details menu options. The popup menu is accessed by right-clicking a field in a data form that has the field popup menu symbol displayed in its field textbox. User-Defined Field Popup Menu For any field in a data form, you can specify a popup menu that is accessed by right-clicking the field in the data form. Upon defining a field popup menu, a popup menu symbol is automatically displayed in the field textbox.
36-6

Menu Forms Defining a Popup Menu for a Field in a Data Form

After defining the popup menu, the popup menu can be used for a field in a specific form. Or, the popup menu can be part of a fields definition, such that, the popup menu is used for the field in any form that contains the field. Note the following:

Field popup menus can have nested popup menus (i.e. a field popup menu can invoke a "sub" popup menu). If a nested popup menu exists for a menu option, a right-arrow symbol is displayed alongside the menu option. If the menu option invokes a form, an ellipsis symbol (...) is displayed alongside the menu option. All field popup menus have the same look and feel that is dictated automatically by the system. Therefore, GUI definitions specified for a field popup menu on the Popup Menu Definition form are ignored. A popup menu cannot be defined for a field in a menu form. Popup menus for fields can be disabled via eMerge Client Administration global options. See eMerge Client Installation & Administration Guide. If you want to access the default Internet Explorer popup menu, <Ctrl>+right-click the field.

To define a user-defined field popup menu:

1 From the Presentation tab, right-click the Forms node and choose the New Popup Menu Form option. The Popup Menu Definition form is displayed:

36-7

36

Menu Forms Defining a Popup Menu for a Field in a Data Form

2 Define the field popup menu and the menu options for the field popup menu. 3 Optionally, assign the Separator option to each menu option for which you want to display a separator. The separator is displayed on the popup menu below the display of the menu option. 4 To add an image for a menu option for the popup menu: 1. Put the cursor on the needed menu option and click the Image button. The Popup Menu Option Image form is displayed:

36-8

Menu Forms Defining a Popup Menu for a Field in a Data Form

2. Click the button next to Menu Option Icon to select the image file needed and then click OK. The image selected is used as the icon for the menu option when the popup menu is invoked. Before changing the menu option icon, read "Adding Images to a Form" on page 34-23.

To define a field popup menu for a field in a specific form:

1 Display the form that contains the field where the field popup menu is needed. 2 Via Form Editor, right-click the needed field and choose Properties. The Field in Block form is displayed:

36-9

36

Menu Forms Defining a Popup Menu for a Field in a Data Form

3 In the Popup Menu field enter the number of the popup menu defined for the field and click OK.

To define a field popup menu for a field in any form that contains the field:

1 From the Concept form, select the Field tab. 2 Click the GUI button. The Field GUI form is displayed:

36-10

Menu Forms Defining a Popup Menu for a Field in a Data Form

3 In the Popup Menu field enter the number of the popup menu defined for the field and click OK.

36-11

36

Menu Forms Defining a Popup Menu for a Field in a Data Form

36-12

Chapter 37 Tree Compound Forms

A tree compound form consists of two frames: One frame contains the tree form (i.e. the tree control) and one contains a data form. The tree compound form is used as the "top form" for an application. A list of items is presented to the end user in a tree. The user can expand or contract the nodes to view or hide a list of sub-items: Tree Form Data Form

Tree Compound Form You can specify the layout for the forms in the tree compound form: horizontalthe called forms are placed one above the other. verticalthe called forms are placed alongside each other.

37-1

37

Tree Compound Forms Creating a Tree Compound Form

37.1 Creating a Tree Compound Form

A tree compound form is created by defining the tree compound form and the tree form and data form that are included in the form.

To create a tree compound form:

1 From the Presentation tab, right-click Forms and choose New Compound Form. The Tree Compound Form Definition form is displayed:

2 Enter a number for the tree compound form in the Form No. textbox. 3 Enter a name for the tree compound form in the Name textbox. 4 In the Tree Form subgroupbox enter the number of the tree form:

If defining an existing tree form, unassign the New option. If defining a new tree form, do not unassign the New option and click the Zoom button to define the form.

37-2

Tree Compound Forms Modifying a Tree Compound Form

5 In the Initial Form subgroupbox enter the number of the data form that is going to be displayed in the Work Pane. If you want to define a new data form as the Initial Form, click the New button. 6 Select the Split Type for the tree compound form:

horizontalthe Tree form and the Initial Form are placed alongside each other. verticalthe Tree Form and the Initial Form are placed one above the other.

7 Click Apply to save the form and then click Display to display the form.

37.2 Modifying a Tree Compound Form

To modify a tree compound form:

1 Using Form Editor, right-click the form and choose Compound Form Properties from the popup menu. The Tree Compound Form Definition form is displayed. 2 Modify any definitions you require. To modify the data form of the tree compound form click arrow next to the Form Editor toolbar button and select Form Editor for Form in Work Pane. To modify the tree form of the tree compound form or the tree compound form definition, click the Form Editor toolbar button or select Form Editor from the menu selected.

37.3 Tree Forms

A tree form is one of the forms displayed via a tree compound form. A tree form displays a hierarchy of nodes that display metadata and data. The nodes can be:

expanded double-clicked right-clicked

In order to work without a mouse in an eMerge Client tree control, the <Application> key ( ) can be used in place of the right-mouse key and the <Enter> key can be used in place of selecting (double-clicking) with the mouse. Note that when working with i.way, <Shift>+<F10> can be used instead of the <Application> key.

37-3

37

Tree Compound Forms Tree Forms

Expand a Node

Upon expanding a node, other nodes belonging to the expanded node, are displayed: nodes metadata

data

Double-click a Node

Upon double-clicking a node, objects can be invoked (e.g. a form object opened).

Right-click a Node

Upon right-clicking the node, a popup menu is displayed. By default the popup menu displays the following option categories:

open delete new refresh

The popup menu can be customized to display additional options and/or to display only part of the default options:

37-4

Tree Compound Forms Tree Forms

See "Customizing a Popup Menu" on page 37-16 for more details on customizing a popup menu.

Creating a Tree Form

A tree form is created by specifying its hierarchy of nodes and the objects opened or inserted when clicking the nodes, as well as the called programs, queries or operations that are required for the functionality of the nodes. The information required for the tree form definition is specified via nodes. Each node represents a block in the tree form. A node can do the following:

Display a node on the tree form. Provide for form objects to be opened or inserted from a node. Invoke a program, query or operation that retrieves data from the knowledgebase that is displayed in the tree form (e.g. a list of forms).

To create a tree form:

1 From the Presentation tab, right-click Forms and choose New Tree Form. The Tree Form Definition form is displayed:

2 Enter a number for the tree form in the Form No. textbox. 3 Enter a name for the tree form in the Name textbox.

37-5

37

Tree Compound Forms Tree Forms

Nodes groupbox

In the Nodes groupbox the names of the nodes to be used in the tree form are defined. The name of a node can be:

displayed in the tree formIf no operation, program, or query is assigned to the node, the name for the node is displayed in the tree form as metadata (the name of a node). not displayed in the tree formIf an operation, program, or query is assigned to the node, the name of the node is not displayed in the tree form. The node will invoke the program, query, or operation. For example, a list of rulesets defined in the knowledgebase can be displayed in the tree form via a query or operation.

4 Enter a sequential number for the node in the No. textbox. 5 Enter the name of the node in the Name textbox. 6 In the Tree textbox enter the number of the tree form invoked (and displayed) when the current node is expanded. A hierarchy tree of nodes is obtained by repeatedly defining a dependent tree form for a dependent tree form.

The dependent tree form referenced must be defined in the knowledgebase. Can be created by assigning the New option.

7 If you want to insert a new object via the node, enter the form number of the object in the New Object textbox of the dependent tree form. From the tree form the object is inserted by right-clicking the node and choosing the New option from the popup menu.
If a New Object Form number is not defined for the node of the dependent tree form, the New option is not displayed on the default popup menu created for the node.

8 If you want to open an object via the node, enter the form number of the object that is invoked, in the Open Object textbox. From the tree form the object is opened by:

Double-clicking the node. Right-clicking the node and choosing the Open option from the popup menu.

If an Open Object Form number is not defined for the node, the Open option is not displayed on the popup menu for the node. Double-clicking the node has no effect.

9 In the Occ textbox enter the number of occurrences displayed when the node is expanded. Only nodes that are generated using operations, queries and programs can have more that one occurrence displayed. The maximum number of occurrences that can be displayed at one time is 29. To view additional occurrences, click the more icon (series of dots at end of the list).

37-6

Tree Compound Forms Tree Forms

It is recommended to enter the maximum number of occurrences (29) in the Occ textbox in order to limit the use of the more icon.

10 Click OK.

Assigning Options to a Node

To assign options to a node 1 Access the Tree Form Definition form and click the Details button. The Tree Node Details form is displayed:

2 Assign any required options to the node. See Form Reference. 3 Click OK.

Limiting the Number of Fields Used by the Node

To limit the fields for a node:

1 Access the Tree Form Definition form, locate the pointer on the node number (or node name) and click the Fields button. The Fields in Node Definition form is displayed listing the fields defined for the node:

37-7

37

Tree Compound Forms Tree Forms

2 Assign any required options to a field in the node. For example, assigning the Ignore option causes the field to be ignored when invoking the node. 3 Click OK.

Copying a Node Definition

The definition for a node can be copied to a new node. All properties of the node are copied. The form being copied to must be a tree form.

To copy an existing node from a form to a new node (in the same form or another form):

1 Access the Tree Form Definition form, locate the pointer on the node number (or node name). 2 Click the CopyToNode button. The Copy to Block/Node form is displayed:

37-8

Tree Compound Forms Tree Forms

3 In the New groupbox, enter the number for the new node and the number and name of the form to which the new node is copied. 4 Click Copy.

To copy an existing node from a form (the same form or another form) to a new node in the form:

1 Access the Tree Form Definition form. 2 Click the CopyFromNode button. The Copy from Block/Node form is displayed:

3 In the From groupbox, enter the number of the node to be copied and the number and name of the form from which the node is copied. 4 In the New groupbox, enter the number for the new node. 5 Click Copy.

Copying a Tree Form Definition

The definition for a tree form can be copied to another tree form.

37-9

37

Tree Compound Forms Modifying a Tree Form

To copy a tree form definition:

1 Access the Tree Form Definition form and click the CopyTree button. The Copy Form form is displayed:

2 In the New groupbox:

Enter the number for the new tree form in the Form No. textbox. Enter a name for the new tree form in the Name textbox.

3 Click OK.

37.4 Modifying a Tree Form

Once a tree form is defined, you can modify the following via the Tree Form Editor:

the tree form definitions

presentation behavior called forms: open, new, dependent tree form, popup menu nodes options foreground color

metadata display

37-10

Tree Compound Forms Modifying a Tree Form

background color font node icon

Modifying Tree Form Definitions

To modify tree form definitions:

1 Click the Form Editor button on the toolbar. 2 In the tree form, right-click the particular node whose definitions you want to modify. A popup menu is displayed:

37-11

37

Tree Compound Forms Modifying a Tree Form

3 Choose Properties. The Tree Node form is displayed:

4 Modify any items you require. 5 Click OK.

Modifying the Metadata Display

To modify the metadata display:

1 Click the Form Editor button on the toolbar. 2 In the tree form, right-click the particular node whose definitions you want to modify. A popup menu is displayed:

37-12

Tree Compound Forms Modifying a Tree Form

3 Select the option you want to modify:

Foreground color (see "To modify the foreground color:" on page 37-13). Background color (see "To modify the background color:" on page 37-14). Font (see "To modify the font:" on page 37-14). Image see "To modify the node icon:" on page 37-15).

4 Click the Save button to save the changes and exit Form Editor.

To modify the foreground color:

1 Choose Foreground Color. The Select Foreground Color dialog box is displayed:

37-13

37

Tree Compound Forms Modifying a Tree Form

2 Select the foreground color you require from the System box. 3 Click OK.

To modify the background color:

1 Choose Background Color. The Select Background Color dialog box is displayed:

2 Select the background color you require from the System box. 3 Click OK.

To modify the font:

1 Choose Font. The Font dialog box is displayed:

37-14

Tree Compound Forms Modifying a Tree Form

2 Select the font characteristics you require:

Select the font type from the Font box. Select the font style from the Font Style box. Select the font size from the Size box

3 Click OK.

To modify the node icon:

1 Choose Image. The Open a File dialog box is displayed:

2 Locate the image file you require for the node icon. 3 Click Open.

37-15

37

Tree Compound Forms Customizing a Popup Menu

37.5 Customizing a Popup Menu

You can customize the popup menu that is displayed upon right-clicking a node. By default the popup menu displays the following menu options:

OpenOnly displayed if an Open Object number is defined for the node. NewOnly displayed if a New Object number is defined for the node. DeleteOnly displayed if the EnableDelete option is assigned to the node via the Tree Node Details form. RefreshAlways displayed.

You can add menu options to the above default menu options. A nested popup menu (i.e. a menu option invokes a "sub" popup menu) can be defined for a menu option in the popup menu defined for a node.

To add menu options to the popup menu displayed:

1 Access the Tree Form Definition form. 2 Enter the number of the popup menu in the Popup Menu textbox.

37-16

Tree Compound Forms Automatic Refresh of the Tree Control

3 Access the Popup Menu Definition form:

4 Enter a number for the popup menu in the Form No. textbox. 5 Enter a name for the popup menu in the Name textbox. 6 In the Menu Options groupbox specify the following for each option displayed via the menu:

In the Called Form textbox, enter the number of the form invoked when selecting the option. In the Displayed Text textbox, enter the text displayed for the option. Optionally, assign Separator to the menu option if you want to display a separator line on the popup menu after the menu option.

7 Click OK.

37.6 Automatic Refresh of the Tree Control

The tree displayed in the Navigation pane of Development Workbench is composed of metadata nodes and data node occurrences. Data nodes are automatically refreshed only when a data occurrence displayed in the tree was deleted. You can instruct eMerge to automatically refresh parts

37-17

37

Tree Compound Forms Automatic Refresh of the Tree Control

of the tree whenever a change is made to a data occurrence (via a form opened from the tree). eMerge automatic refresh behavior means:

If a form is accessed via the Open option on a popup menu, eMerge automatically refreshes the immediate parent node of the current node. If a form is accessed via the New option on a popup menu, eMerge automatically refreshes the current node.

To automatically refresh the tree when field data displayed in the tree is changed:

1 Via Form Editor, right-click the needed field (i.e. the one that is displayed in the tree) and choose Properties. The Field in Block form is displayed. 2 Click Advanced. The Field in Block Advanced form is displayed:

3 Assign the RefreshNode option to the field. 4 If a form is accessed via any other menu option on a popup menu, eMerge automatically refreshes the immediate parent node of the current node. However, if you want the current node to be refreshed instead of the

37-18

Tree Compound Forms Automatic Refresh of the Tree Control

parent node, assign the RefreshCrntNode option to the menu option via the Popup Menu Definition (100632) form:

37-19

37

Tree Compound Forms Automatic Refresh of the Tree Control

37-20

Chapter 38 Select and Detail Forms

For any relationship between two entities (including a dependency relationship), the key field and the name field of one entity can be used to access data from the other entity. That is, a foreign key field and a foreign name field are used to access a select form or a detail form containing data from the foreign entity. Select Forms A select form is a multiple occurrence data form. On accessing the select form, all the existing values for the particular field are displayed. The user can select a value and return to the calling form. Access the select form by:

Double-clicking the foreign key or name field Clicking the Select Value button Clicking the down-arrow to the right of the field control select client select

There are two kinds of select forms:

Detail Forms

A detail form is a single occurrence data form. On accessing the detail form, details of the occurrence having the particular key field or name field are displayed. Access the detail form by clicking the Zoom button, with the cursor positioned on a field in a data entry form or menu.

38-1

38

Select and Detail Forms Select Forms

38.1 Select Forms

Control Select Form
A control select form displays a list of values (from which one may be selected) for the field.

The field is displayed initially as a textbox with a down-arrow to the right of the field. When the user double-clicks the textbox, clicks the arrow at the end of the field, or clicks the Select Value button (with the cursor in the field), the textbox becomes a list of choices.

Client Select Form

A client select form is a multiple occurrence data form. On accessing the client select form, all the existing possible values for the particular field are displayed in a multiple occurrence form. The user can select a value and return to the calling form.

38-2

Select and Detail Forms Detail Form

The field is displayed initially as a textbox. When the user double-clicks the textbox, the user accesses the client select form. To exit a client select form without making a selection, either press <Esc> on the keyboard, or click the Cancel button.

38.2 Detail Form

A detail form is a single occurrence data form. On accessing the detail form, details of the occurrence having the particular key field or name field are displayed.

38-3

38

Select and Detail Forms Enabling Select or Detail Forms

Access the detail form by clicking the Zoom button, with the cursor positioned on a relevant field in a data form or menu. The Zoom button is only available if the cursor is in a field that has a detail form.

38.3 Enabling Select or Detail Forms

For any association between two entities (including a dependency association), the key field and the name field of one entity can be used to access data from the other entity. That is, a foreign key field and a foreign name field are used to access a select form or a detail form containing data from the foreign entity. The multiple occurrence data entry form automatically generated for the entity is defined as the select form. The select form is displayed as a control select form (i.e. as an EditDrop). The single occurrence data entry form automatically generated for the entity is defined as the detail form. However, you can define your own user-defined forms to be used for select or detail forms. A user-defined select form can be used for a control select form and/or a client select form. A user-defined detail form can be used for a client detail form. You can display all the fields or only some of the fields when invoking the select form. Assign the Ignore option to the fields you do not want to display when invoking the select form. You can enable user-defined control select, client select and client detail forms globally or locally. When enabled globally, the forms are accessed from any form containing the field. When enabled locally, the form can be accessed only from the field in a specific form. Just as the control select, client select and client detail forms can be enabled for a particular form (i.e. locally), they can also be disabled locally; i.e. the forms are not accessed from the field in a specific form. Local control select, client select and client detail forms override any global control select, client select and client detail forms defined for the field.

Enabling Select or Detail Forms Globally

1 Via the Concept: Design form, with the cursor in the field for which you want to enable a control select, client select or client detail form, click the FieldDef button. The Field Definition form is displayed.

38-4

Select and Detail Forms Enabling Select or Detail Forms

2 Click the GUI button. The Field GUI form is displayed:

3 In the Forms subgroupbox, enter the form numbers for the forms to be called, in the appropriate textboxes:

Control Select Form Client Select Form Client Detail Form

4 For a control select form, set the Display Type to EditDrop or Listdrop. 5 Press OK to apply the definitions.

38-5

38

Select and Detail Forms Enabling Select or Detail Forms

Enabling Select or Detail Forms Locally

1 Using Form Editor, double-click the field for which you want to enable a control select, client select or client detail form. The Field in Block form is displayed:

2 In the Forms subgroupbox, enter the form numbers for the forms to be called, in the appropriate textboxes:

Control Select Form Client Select Form Client Detail Form

.

3 For a control select form, set the Display Type to EditDrop or Listdrop
The select form specified must already be defined in the knowledgebase.

4 Press OK to apply the definitions.

38-6

Select and Detail Forms Search Order

Disabling Select or Detail Forms Locally

1 Using Form Editor, double-click the field for which you want to disable control select, client select and client detail forms. The Field in Block form is displayed. 2 In the Behavior subgroupbox, assign the NoSelection option. 3 Press OK to apply the definitions.

38.4 Search Order

For Detail Forms
When a user clicks the Zoom button with the cursor on a field, the system searches for a form to display in the following order: 1 The system searches first for a client detail form in the following order:

At the form level as defined in the Field in Block form At the field level as defined in the Field GUI form At the original field level as defined in the Field GUI form of the original field At the form level as defined in the Field in Block form At the field level as defined in the Field Subject form At the original field level as defined in the Field Subject form of the original field

2 The system then searches for the detail form in the following order:

For Select Forms

When a user clicks the Select Value button with the cursor on a field, the system searches for a form in the following order:

Whether the system first searches for the control select form or first searches for the client select form is determined by the WSCTRLSELECT command.

1 The system searches first for a control select form in the following order:

At the form level as defined in the Field in Block form At the field level as defined in the Field GUI form At the original field level as defined in the Field GUI form of the original field

38-7

38

Select and Detail Forms Search Order

2 The system then searches for a client select form in the following order:

At the form level as defined in the Field in Block form At the field level as defined in the Field GUI form At the original field level as defined in the Field GUI form of the original field At the form level as defined in the Field In Block form At the field level as defined in the Field Subject form At the original field level as defined in the Field Subject form of the original field

3 The system then searches for the select form in the following order:

Double-clicking the field or clicking the down-arrow always displays the control select formnot the client select form.

38-8

Chapter 39 Form Actions

When using an application, the user must navigate from one form to another. One way of providing a flow is via a menu which allows the user to choose from a list of options (see Chapter 36, Menu Forms). From within a form, you can define a flow to another form by defining a form action that calls another form. A form action may be invoked in several ways:

By clicking the action button on the form By choosing the option from a menu bar or a right-click menu By pressing the keyboard function key, if one has been defined

When a form is called from another form, (either a menu form or a data form) eMerge maintains information about the calling form. When you exit the called form by clicking the Quit button, the calling form is redisplayed. In the example below, the user invokes Form B from Form A. When the Quit button is clicked, the user returns to Form A.

Form actions may also execute a command.

39-1

39

Form Actions Adding a Form Action to a Form

By default, the form for a parent concept, created via a constructor includes form actions to access all its dependent forms. For example an employee concept has the structure shown below:

The form created from the concept would show the relevant form actions:

39.1 Adding a Form Action to a Form

You can define form actions in a form to perform a command or to access a form.

To define an action:

1 Display the form you want to modify. Using Form Editor, click the Insert Action button. Click the form where you want the action button to be, and drag to create the correct button size (this can be adjusted later).

39-2

Form Actions Adding a Form Action to a Form

2 Right-click the action button and choose Properties. The Action Definition form is displayed:

3 The Action No. field is used if the same action is to be accessible from a keyboard function key as well. Enter the function key number here.

Function keys 1 to 8 are reserved. You cannot modify these except to assign them the Ignore or NoDisplay options. See "Action Inheritance" on page 39-8 for a description of these options. You can define function keys greater than 24, but these can only be invoked by using the name as a BLP command.

4 Enter the name to be associated with the action. The name attached to the action can be used as a command to perform the action. 5 Either enter the form number of the form to be accessed in the Called Form/Block field, or enter the BLP command to be executed in the BLP Command field. The specified form or BLP command is invoked when the user clicks the form action (or presses the assigned function key). 6 If you are calling a specific block in a form flow, specify the relevant block number in the second field of Called Form/Block. 7 Click OK.

39-3

39

Form Actions Adding a Form Action to a Form

Display a Form Action as an Image

You can hide the Name and the Displayed Name defined for a form action, so that the form action is displayed only as an image.

To hide the Name and Displayed Name of a form action:

1 Using Form Editor, double-click the action. The Action Definition form is displayed:

2 Assign the NoDisplayName option.

3 Click OK to save the changes and exit from Form Editor.

Only an image is displayed as the form action:

The ClientOnly option is automatically assigned when NoDisplayName is assigned.

39-4

Form Actions Tooltips for Form Actions

39.2 Tooltips for Form Actions

A tooltip can be defined for a form action. A tooltip is textof up to 78 characters in length per languagethat is displayed when the pointer passes over a specified form object.

To create a tooltip for a form action:

1 Double-click the button of interest. The Action Definition form is displayed. Enter the tooltip text in the Text field for the language you want:

2 Save the changes. The tooltip is displayed when the pointer passes over the form action:

39-5

39

Form Actions Access Key for Action Buttons

39.3 Access Key for Action Buttons

You can define an access key for a button action on a form. An access key is any letter in the alphabetof the language selected that is not already being used for another button in the formused with the <Alt> key to invoke the button action.

If the access key is a letter in the name of the button, the access key letter is displayed underlined on the button:

If the access key is not a letter in the name of the button, the access key letter is displayed on the button within parentheses at the end of the button name:

39-6

Form Actions Access Key for Action Buttons

To define an access key for a button:

1 Using Form Editor, double-click the button on the form for which you want to define an access key. The Action Definition form is displayed:

2 Enter the letter for the access key in the Access Key field (located in the Displayed Names subgroupbox) and click OK. The access key is displayed on the button within parentheses at the end of the button name.

The access key can be any letter in the alphabet of the language selected that is not already being used for another button in the form. The access key does not have to be a letter in the name of the button. When the letter defined for an action key appears more than once in the button name, the first occurrence of the action key in the button name is the one that is underlined on the button display.

39-7

39

Form Actions Action Inheritance

3 Exit Form Editorto see the access key displayed as part of the button action.

39.4 Action Inheritance

In the normal flow between forms, each action on a form is inherited automatically by the forms it calls. For example:

Form A has actions to call form B or form C. When Form B is called it inherits the action that calls form C.

Calling a Form Empty of Data

Normally, when you create a chain of forms (by accessing one form from another), if you access a form already in the chain, the flow returns to the most recent occurrence of the form in the flow. The form is displayed with the original data. To have the form displayed empty of values, assign the NewForm option to the relevant function button, in the Action Definition form.

39-8

Form Actions Action Inheritance

Example: The following diagram shows two forms, A and B. Each of them has a function button defined to access the other:

In form A, Go to B is defined to access form B and in form B Go to A is defined to access form A.

Ignoring Inheritance When Quitting a Form

NewForm has a different function in a case where an action that calls a form (Form C) is invoked, not from the form where it was defined (Form A), but from a form lower down in the chain (e.g. Form B), which inherited the action. Via action inheritance, a form action that is inherited by a form acts as if it was defined for the form. On quitting the form you return to the calling form. If you want to return to the form where the form action was initially defined, assign the NewForm option on the action. Example when NewForm is not specified In the default situation (when NewForm is not assigned), Form B inherits the Go to C form action from Form A. Go to C is used to access Form C, and in this case Form C is accessed from Form B. On clicking the Quit button from Form C, you return to Form B:

39-9

39

Form Actions Action Inheritance

Example when NewForm is assigned

If, in Form A, you define Go to C with the NewForm option, on clicking the Quit button from Form C, you return to Form A. Form B is removed from the form chain:

Stopping Inheritance
A form action, defined in one form, is available on any form called from it, except in the following circumstances:

The form action calls the form that is currently displayed. The form action function key is assigned a different definition in the current form. The NoDisplay option is assigned to the action. The action button is not displayed but issuing the command still executes the function. The Ignore option is assigned to the action. The action button is not displayed and issuing the command does not execute the function. The LocalAction option is assigned. The inheritance mechanism for the form action is deactivated.
Consider deactivating the inheritance of function buttons if the amount of information shown on each form is small. If you keep the inheritance feature, you can end up with more function buttons than fields.

39-10

Form Actions Defining the Enter Key as an Action

39.5 Defining the Enter Key as an Action

You can define an action that is executed when the user presses <Enter>. 1 Using Form Editor, define the action and note the action number. 2 Access the Block form. 3 Enter the number of the action in the Enter As Action field. 4 Click OK. Executing <Enter> and an Action Together When the user clicks an action button, the default situation is that if changes have been made to the data on the form, the changes are ignored and the action is performed. To change the default so that changes to the form are always updated in the database before an action is performed, issue the ACCEPT ALL command.

To issue the ACCEPT ALL command:

1 Go to the command text box on the toolbar and type accept all:

2 Press <Enter> to execute the command.

You can still separate the execution of the action and the updating of the data by assigning the Delay option on a specific action. In this case, the data is not updated until you press <Enter>. Return to the default by issuing the ACCEPT OFF command.

39-11

39

Form Actions Defining the Enter Key as an Action

39-12

Chapter 40 Presentation Components for Forms

You can define presentation components for your eMerge application. Using presentation components, you can implement interoperability with other applications and you can enhance the appearance and functionality of a form. Some uses of presentation components are:

enabling and disabling interactive elements within a form controlled animations showing graphs instead of tables of data adding special controls

Presentation components are introduced into the eMerge knowledgebase accompanied by a set of parameters, properties and methods or functions via eMerge forms. The technology (i.e. category) on which the component is based (e.g. JavaApplet or ActiveX) determines the nature of the set of definitions that accompanies the component. Once components are introduced into the knowledgebase, you can create each instance (i.e. use) of the component in various forms. Each component or component instance can be used more than once in a form, and in more than one form. You can use a component that is already available, or you can create your own component, according to application requirements. For most available components, a preparing component is needed in order to adjust the available component to the specific requirements of the application. This chapter is an overview of the use of components within eMerge and how to utilize a component, according to the technology (category) on which the component is based. Appendix e, Examples of Presentation Components describes specific examples of components.

40-1

40

Presentation Components for Forms Interoperate with Other Applications

40.1 Interoperate with Other Applications

You can work dynamically with external applications and components, both web-based and desktop. Your eMerge application can interoperate with other applications by defining them as components within an application.

Web-based applications and components can be within the same browser instance (but in another frame) or within another browser instance. In either case, you use the Document Modeling Editor (DOM) to transfer information. Note that data can be transferred only between windows or frames that share the same domain. For desktop applications, use OLE Automation with a script to transfer information.

Example: Components can be used to transfer data between applications: You can provide a script that transfers data from an eMerge form to an Excel spreadsheet while both are open on the desktop. Each change to the data in the eMerge form can be reflected automatically in the spreadsheet and in the graphs generated by the spreadsheet. Note that as a security restriction, data can be transferred only between windows or frames that share the same domain.

40.2 Enhance Appearance and Functionality

You can modify the display of your forms in order to enhance your application. Components enable images to be shown rather than lists, or graphs to be shown rather than tables of data. Following are some examples of how components can enhance your form display: Display an Image Map In a personal details form, a customer specifies the country in which he lives:

40-2

Presentation Components for Forms Enhance Appearance and Functionality

Once the country is specified, the customer clicks the State/Province button. In an unenhanced application, the list of provinces in Canada is displayed, from which the customer can select:

The selected state/province is displayed in the personal details form. In an enhanced application, the component replaces the list of provinces with a map that shows the provinces; i.e. clicking the State/Province button activates a component that displays a map of Canada:

40-3

40

Presentation Components for Forms Enhance Appearance and Functionality

The customer clicks on a province, and the name of the province is displayed in the personal details form:

Thus, the component does the following: displays the map of Canada enables the customer to select a province sends the result to the personal details form Display a Date Control In an enhanced application, instead of a textbox, the component displays a calendar from which the user can select the year, the month and the date, instead of typing them.

Change Background Color

A fields background color can change according to the value entered.

See how to utilize this example in "Script Component" on page e-6.

40-4

Presentation Components for Forms Enhance Appearance and Functionality

Branch to E-Mail

An application requires that email confirmation is sent to a customer. The email letter can be displayed automatically with the appropriate name and address of the customer.

40-5

40

Presentation Components for Forms Enhance Appearance and Functionality

Show Appropriate Pictures

A displayed picture on a form can change, depending on the highlighted field. Each time the cursor is positioned in a particular row of a form, the appropriate picture is displayed.

Show a Graph Rather than a Data Table

Statistics can be displayed in a visual graph, instead of in a list.

See how to utilize this example in "JavaApplet Component" on page e-13.

40-6

Presentation Components for Forms How to Utilize a Component

Branch to HTML Page

An HTML page can be displayed by clicking a button. Clicking the Summary button, on the car details form below, displays an HTML page.

See how to utilize this example in "URL Component" on page e-1.

40.3 How to Utilize a Component

Utilizing presentation components consists of four major steps:

40-7

40

Presentation Components for Forms How to Utilize a Component

Components within the Knowledgebase

This diagram shows the presentation components within the knowledgebase:

Prepare the Component

Decide whether you are using a component that is already available, or you are creating your own component, according to the application requirements. If you are using an already available component, you probably need a preparing component in order to adjust the available component to the specific requirements of the application. The preparing component can: activate the component transfer data from one component to another transfer data from the eMerge knowledgebase to the component enable access to eMerge form elements Example: For a component that displays a graph showing dynamic values, a SCRIPT component (a data table) is used to transfer data to the available JavaApplet component (a visual graph). See "Show a Graph Rather than a Data Table" on page 40-6. Use the browser Document Modeling Editor (DOM) to prepare components. The browser DOM has been extended in order improve its functionality for eMerge requirements.
40-8

Presentation Components for Forms How to Utilize a Component

DOM Extensions Used for eMerge Forms

Enables access to eMerge objects (e.g. form objects, field objects, possible value object, enumerator object,...) and allows performing functions (e.g. checkValue, getActiveField, logoff, openNewForm, ...). See General Reference for an explanation of the types of eMerge blocks.

Introduce the Component into the Knowledgebase

Introduce components into the eMerge knowledgebase from the Presentation tab via the components node in the tree. Each component has a Component Id to identify it in the knowledgebase. The same component can be used more than once within a form, as well as in more than one form. You may have to define functions or methods as part of the set of parameters that accompany the introduced component.

Create an Instance and Place it in the Form

Create an instance for each use of a component in a form. Each use of a component is a component instance, and is identified by its Instance ID. Create the instance via the Components in Form form. For a visible component, define the position and size (using Form Editor) in the form, before creating the instance. Each indication of position and size is identified by a Instance ID. Note that the same Instance ID can be used for more than one component or component instance in the form. The position and size of an instance can also be indicated via a script. The script indication of the position and size overrides the Instance ID. Example:
STYLE=\"Position:absolute;LEFT:225;TOP:453;WIDTH:74;HEIGHT:70;\"

You may have to define functions or methods as part of the set of parameters that accompany the instance. Some of the definitions of a component can be overridden for a particular instance (i.e. use) of the component.

Attach an Event to a Form Object and Choose a Component Instance

Access the definition form for a particular form object, select an event, and choose the event handler that is attached to the form object. A form object can be one of the following:

form
40-9

40

Presentation Components for Forms How to Utilize a Component

field button menu option image

An event controls when a component instance, that is attached to a form object, is activated. The event handler is made up of the number and name of the instance, the component, the interface (if any) and the function or the method. Thus, an instance that is attached to an event must consist of definitions for functions or methods. Example: For the enhancement in which clicking a button displays a map, the State/Province button is a form object. The event is the clicking on the form object, i.e. the State/Province button. The event activates the component that displays of the map of Canada. The following table shows the set of events that are possible for each form object type, and the corresponding set of JavaScript events: Event OnAbort OnChange OnClick OnDblClick OnFocus OnFocusLost OnKeyDown OnKeyPress OnKeyUp OnLoad OnMouseDown OnMouseMove OnMouseOut OnMouseOver OnMouseUp OnResize 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 Form Field Button Menu Option Popup Menu JavaScript Option 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3

40-10

Presentation Components for Forms Supported Categories

Event OnSelect OnUnLoad 3

Form 3

Field

Button

Menu Option

Popup Menu JavaScript Option 3 3

Unattached Component Instances for Forms

If a component instance is created for a form, but it is not attached to a form object and an event, the instance is activated automatically when the form is displayed. The instance remains active as long as the form is displayed. Example: A calendar can be displayed as part of a form. There are no events attached to the form. That is, the calendar is displayed as long as the form is displayed.

40.4 Supported Categories

The technology (i.e. category) on which the component is based determines the nature of the set of definitions that accompanies the component. The supported categories are: URL The internet address of a component. Using this category, you can activate a component by indicating its URL. SCRIPT Scripts can be written in any language that is supported by the browser. The SCRIPT category is recommended for components that implement other components, i.e. the preparing components. JavaApplet A component written in Java. You can prepare a new Java component, or use an already available one. JavaApplet is an open, secure tool, though it requires a full procedure of programming and compilation. ActiveX Programmable elements that enable you to choose from a wide range of language tools, applications and reusable parts in order to enhance a users interaction with the application. An ActiveX control can be accessed only if it is installed on the web clients local computer. The following table shows where to find an explanation on how to utilize a component for each category, and an example for each one:

40-11

40

Presentation Components for Forms Utilizing a URL Component

Category URL SCRIPT ActiveX

How to Utilize page 40-12 page 40-19 page 40-35

Example page e-1 page e-6 page e-13 page e-21

JavaApplet page 40-26

40.5 Utilizing a URL Component

Preparing the Component
Prepare the component and ensure that it is located at the required address.

Defining a URL Component in the Knowledgebase if it Uses eMerge Fields

If a URL component includes definitions for eMerge fields that serve as parameters, introduce the URL component into the knowledgebase.

40-12

Presentation Components for Forms Utilizing a URL Component

Otherwise, it is not necessary to introduce the component into the knowledgebase. 1 From the Presentation tab of the Navigation Pane of Development Workbench expand Integration and right-click Components:

40-13

40

Presentation Components for Forms Utilizing a URL Component

2 Select New URL. The URL (818) form is displayed:

3 Enter a unique identifying number and a name for the component in the Component textboxes. 4 Enter the URL of the component in the Resource textbox. 5 In the Target textbox, specify the name of the browser instance in which the external URL is to be displayed.

If a browser instance with the specified name is open, the component is displayed in that instance. If a browser instance with the specified name does not exist, a new browser instance opens with the specified name. If you do not specify a target name, the component is displayed in the i.way window.

6 Enter the eMerge fields that serve as the parameters of the component.

40-14

Presentation Components for Forms Utilizing a URL Component

The component parameters defined here are be used by all component instances. You can, when defining an instance for a component, customize the parameters for the particular component instance (see "Creating an Instance for a Form" on page 40-15). ParameterField No. parameter. Identifying number of the field that serves as a Name of the field that serves as a parameter.

Parameter Field Name

Name In Component Name of the parameter as it appears in the URL. This name serves as an alias. If it is not defined, the original field name is used. Value A constant value for the field. This parameter is optional. If it is not defined, the field is used without a constant value. 7 Click OK.

Indicating a Component Location ID for a Visible Component

If the component is a visible component, indicate the position and size in the form before creating the instance. Each indication of position and size is identified by a COMPONENT LOCATION ID (i.e. GUI ID). 1 Access the form in which you want to place the component and click the Form Editor button. 2 Click the Insert Component button. 3 Place the pointer where you want the component to appear in the form, drag and click. A rectangle appears. Resize the rectangle, if necessary, by dragging the rectangle handles. 4 Click Save, to save the component location information. Note the number shown in square brackets on the status bar. This is the COMPONENT LOCATION ID for the visible component. Record this number for future use. The same COMPONENT LOCATION ID can be used for more than one component or component instance in a form. 5 Save and close Form Editor.

Creating an Instance for a Form

The procedure for creating an instance depends on whether the URL is visible and whether it uses eMerge fields as parameters.

40-15

40

Presentation Components for Forms Utilizing a URL Component

1 Access the form in which you want to place the component and click the Form Editor button. 2 Right-click in the form and choose Properties from the pop-up menu that is displayed. The Form Definition (10647) form is displayed. 3 Select the Components tab:

4 Enter a unique instance ID and an instance name for the component instance in the Instance textboxes. 5 Select the Category:

Select URL for an instance of a URL component that includes eMerge fields that serve as parameters. Select Direct URL for an instance of a URL component that does not include eMerge fields that serve as parameters. Note that this type of instance does not require introducing into the knowledgebase.

6 Select the Component ID you want. The Component ID and the Component Name are displayed. 7 For a visible component that is indicated by a COMPONENT LOCATION ID, select the COMPONENT LOCATION ID that was assigned for this instance in the form. See "Indicating a Component Location ID for a Visible Component" on page 40-15. 8 If the component includes definitions for eMerge fields that serve as parameters and you want to customize the parameter definitions for the

40-16

Presentation Components for Forms Utilizing a URL Component

component instance, click the InitParms button. The URL: initial Parameters (10663) form is displayed:

Click the Parameter Field listbox and select the fields that are used as parameters of the instance. Indicate the name of the parameter field in the component via the Name in Component textbox. 9 Save and exit all forms and close Form Editor.

Attaching the Component Instance to an Event

An event controls when a component instance is activated. If a component instance must be activated as long as the form is displayed (not depending on any events), do not perform this procedure. 1 Access the form in which you want to place the component and click the Form Editor button. 2 Access the definition form for the form object. Right-click with the pointer positioned in the form object (as noted in the table below) and choose Properties from the pop-up menu that is displayed. The form displayed depends on the form object (as listed below). This table shows where to position the pointer and which form is displayed:

40-17

40

Presentation Components for Forms Utilizing a URL Component

Form Object Form Field Action Menu Option Popup Menu Option

Position the Pointer In form (background) In a field Anywhere In a Menu option In a Popup Menu option

Definition Form Form Definition Field in Block Action Definition Menu: Option Definition Popup Menu Definition

For a field, an action and a menu option object you can double-click the object to access the definition form. 3 Select the Events tab. The Events tab displays the following fields, enabling you to attach the component (an external handler) to an event:

Instance ID

Interface ID
Function/Method ID

Instance Name

Component Interface Function/Method Name Name Name

4 Select an event for the form object from the Event listbox. 5 Select the component Instance ID that is attached to the event. 6 Select the number of the action that is assigned to the event from the Action No. listbox. 7 To define component (handler) parameters, select the Components tab. Fill in the fields as described in "Creating an Instance for a Form" on page 40-15. If you need to create a new component, click the NewComponent button. 8 Save and exit all forms and close Form Editor.

40-18

Presentation Components for Forms Utilizing a SCRIPT Component

40.6 Utilizing a SCRIPT Component

Preparing the Component
Prepare the component and ensure that it is located at the required address. See Form Reference for information on how to prepare the component.

Defining a SCRIPT Component in the Knowledgebase

1 From the Presentation tab of the Navigation Pane of Development Workbench expand Integration and right-click Components:

2 Select New Script. The Insert Script dialog box is displayed:

Select the script files you require from the directories listed or click Import to obtain a script file from a directory not listed. Click OK.
40-19

40

Presentation Components for Forms Utilizing a SCRIPT Component

The Script (838) form is displayed:

3 The scripts selected via the dialog box are listed under the Local Knowledgebase node (right pane of window). To introduce a script and/or its methods to the eMerge knowledgebase, select and drag to the Business Integrity Server node (left pane of window). 4 Enter a unique identifying number for the component in the Script No. textbox and press <Enter>:

40-20

Presentation Components for Forms Utilizing a SCRIPT Component

5 To add, delete, or change any script properties and their values, rightclick the script name and select Script Properties:

Name Name of the property as it appears in the HTML specifications for the SCRIPT tag. Value Value of the property.

The component parameters defined here are used by all component instances. You can, when defining an instance for a component, customize the parameters for the particular component instance (see "Creating an Instance for a Form" on page 40-23).

40-21

40

Presentation Components for Forms Utilizing a SCRIPT Component

6 To add or to remove any embedded components, right-click the script name and select Embedded Components:

Verify that the embedded component number and embedded component name are listed in the Number and Name textboxes respectively. If the number or name is missing, add the missing component information by clicking the Add button. The Add Embedded Component dialog box is displayed:

Select the type of the component to add from the Select Component Type listbox, select the required component information, Number and Name, and click OK

Click OK.

7 Enter the URL of the SCRIPT source file in the Source textbox and click OK.

Indicating the Component Location ID for a Visible Component

If the component is a visible component, indicate the position and size in the form before creating the instance. Each indication of position and size is identified by a COMPONENT LOCATION ID (GUI ID).
40-22

Presentation Components for Forms Utilizing a SCRIPT Component

1 Access the form in which you want to place the component and click the Form Editor button. 2 Click the Insert Component button. 3 Place the pointer where you want the component to appear in the form, drag and click. A rectangle appears. Resize the rectangle, if necessary, by dragging the rectangle handles. 4 Click Save, to save the component location information. Note the number shown on the status bar for the COMPONENT LOCATION ID for the visible component. Record this number for future use. The same COMPONENT LOCATION ID can be used for more than one component or component instance in a form. 5 Save and close Form Editor.

Creating an Instance for a Form

The procedure for creating an instance depends on whether the component is visible, whether the script includes properties that are within the HTML specifications for the SCRIPT tag, and whether the component instance uses functions. 1 Access the form in which you want to place the component and click the Form Editor button. 2 Right-click in the form and choose Properties from the pop-up menu that is displayed. The Form Definition (10647) form is displayed. 3 Select the Components tab:

4 Enter a unique instance ID and an instance name for the component instance in the Instance textboxes. 5 Select Script for the Category.

40-23

40

Presentation Components for Forms Utilizing a SCRIPT Component

6 Select the Component ID you want. The Component ID and the Component Name are displayed. 7 For a visible component that is indicated by a COMPONENT LOCATION ID, select the COMPONENT LOCATION ID that was assigned for this instance in the form. See "Indicating the Component Location ID for a Visible Component" on page 40-22. 8 If the component includes properties that are within the HTML specifications for the SCRIPT tag and you want to customize the parameter definitions for the component instance, click the InitParms button. The Script: initial Parameters (10664) form is displayed:

Enter a name for the property in the Property Name textbox. Select a value for the property from the Value listbox. Click OK. 9 An instance that is attached to an event, must have definitions for functions. If the component instance uses functions, click the NewComponent button on the Components tab to display the Script (838) form. Select the functions that are required for the instance. 10 Save and exit all forms and close Form Editor.

40-24

Presentation Components for Forms Utilizing a SCRIPT Component

Attaching the Component Instance to an Event

An event controls when a component instance is activated. If a component instance must be activated as long as the form is displayed (not depending on any events), do not perform this procedure. 1 Access the form in which you want to place the component and click the Form Editor button. 2 Access the definition form for the form object. Right-click with the pointer positioned in the form object (as noted in the table below) and choose Properties from the pop-up menu that is displayed. The form displayed depends on the form object (as listed below). This table shows where to position the pointer and which form is displayed: Form Object Form Field Action Menu Option Popup Menu Option Position the Pointer In form (background) In a field Anywhere In a Menu option In a Popup Menu option Definition Form Form Definition Field in Block Action Definition Menu: Option Definition Popup Menu Definition

For a field, action and menu option object you can double-click the object to access the definition form. 3 Select the Event tab to access the events information. The Events form displays the following fields, enabling you to attach the component (an external handler) to an event:

Instance ID

Interface ID
Function/Method ID

Instance Name

Component Interface Function/Method Name Name Name

40-25

40

Presentation Components for Forms Utilizing a Java Applet Component

4 Select an event for the form object from the Event listbox. 5 Select the component Instance ID that is attached to the event. 6 If the form object attached to the event is an action, attach the event to the action by selecting the number of the action from the Action No. listbox. 7 To define component (handler) parameters, select the Components tab. Fill in the fields as described in "Creating an Instance for a Form" on page 40-23. If you need to create a new component instance, click the NewComponent button. 8 Save and exit all forms and close Form Editor.

40.7 Utilizing a Java Applet Component

Preparing the Component
Prepare the component and ensure that it is located at the required address. See Form Reference for information on how to prepare the component.

Defining the JavaApplet Component in the Knowledgebase

1 From the Presentation tab of the Navigation Pane of Development Workbench expand Integration and right-click Components:

40-26

Presentation Components for Forms Utilizing a Java Applet Component

2 Select New JavaApplet. The JavaApplet (820) form is displayed:

3 Enter a unique identifying number and a name for the component in the Component textboxes. 4 Specify property options for the JavaApplet component. When you create an instance for this component, some of the properties defined for the instance can override the components initial properties. Format
OBJECT

Specifies whether the component tag is an APPLET tag or an tag. The default is APPLET. Name of the file containing the compiled JavaApplet class. Base URL for the application.

Code

Codebase Width Height

Default width of the component, in pixels. Default height of the component, in pixels.
40-27

40

Presentation Components for Forms Utilizing a Java Applet Component

Data

URL that refers to the object's data address.

Click OK. 5 Select the Additional Properties tab. Use this to define any additional properties, other than those that are defined as base properties.

Name Value

Name of the additional property. Value of the additional property.

Click OK. 6 Enter the methods that are used in the component via the Methods tab. No Identifying number of the method of the component. Name of the method as it is defined in the component.

Name

40-28

Presentation Components for Forms Utilizing a Java Applet Component

7 Click the Parameters button on the Methods tab to display the Parameters (816) form. Use this form to define eMerge fields that serve as initialization parameters in the JavaApplet component.

Field No. Name

Identifying number of the field that serves as a parameter.

Name of the field that serves as a parameter.

Value Constant value for the field. This parameter is optional. If it is not defined, the field is used without a constant value. Click OK. The component parameters defined here are be used by all component instances. You can, when defining an instance for a component, customize the parameters for the particular component instance (see "Creating an Instance for a Form" on page 40-30). 8 Enter the related components, if any, via the Embedded Components tab. Category Category of the related component (i.e. URL, SCRIPT, JavaApplet or ActiveX). No Identifying number of the related component. Name of the related component.

Name

40-29

40

Presentation Components for Forms Utilizing a Java Applet Component

9 Click OK.

If the JavaApplet component is invoked via a script, define the JavaApplet component as an embedded component of the script.

Indicating a Component Location ID for a Visible Component

If the component is a visible component, indicate the position and size in the form before creating the instance. Each indication of position and size is identified by a COMPONENT LOCATION ID (GUI ID). 1 Access the form in which you want to place the component and click the Form Editor button. 2 Click the Insert Component button. 3 Place the pointer where you want the component to appear in the form, drag and click. A rectangle appears. Resize the rectangle, if necessary, by dragging the rectangle handles. 4 Click Save, to save the component location information. Note the number shown in square brackets on the status bar. This is the COMPONENT LOCATION ID for the visible component. Record this number for future use. The same COMPONENT LOCATION ID can be used for more than one component or component instance in a form. 5 Save and close Form Editor.

Creating an Instance for a Form

The procedure for creating an instance depends on whether the component includes properties that are within the HTML specifications for the Java Applet tag, and whether it uses methods. 1 Access the form in which you want to place the component and click the Form Editor button. 2 Right-click in the form and choose Properties from the pop-up menu that is displayed. The Form Definition (10647) form is displayed.

40-30

Presentation Components for Forms Utilizing a Java Applet Component

3 Select the Components tab:

4 Enter a unique instance ID and an instance name for the component instance in the Instance textboxes. 5 Select JavaApplet for the Category. 6 Select the Component ID you want. The Component ID and the Component Name are displayed. 7 For a visible component that is indicated by a COMPONENT LOCATION ID, select the COMPONENT LOCATION ID that was assigned for this instance in the form. See "Indicating a Component Location ID for a Visible Component" on page 40-30. 8 If the component includes properties that are within the HTML specifications for the JavaApplet tag, or definitions for eMerge fields that serve as parameters and you want to customize the parameter

40-31

40

Presentation Components for Forms Utilizing a Java Applet Component

definitions for the component instance, click the InitParm button in the Component form. The Initial Parameters (10661) form is displayed:

From the Property Name textbox, select the properties that are required for the instance. From the Parameter Field textbox, select the fields that are required as parameters of the instance. Click OK 9 An instance that is attached to an event, must consist of definitions for methods.

40-32

Presentation Components for Forms Utilizing a Java Applet Component

If the component instance uses methods, click the NewComponent button in the Component form to display the JavaApplet (820) form:

From the Methods tab, select the methods that are required for the instance. 10 Save and exit all forms and close Form Editor.

Attaching the Component Instance to an Event

An event controls when a component instance is activated. If a component instance must be activated as long as the form is displayed (not depending on any events), do not perform this procedure. 1 Access the form in which you want to place the component and click the Form Editor button.

40-33

40

Presentation Components for Forms Utilizing a Java Applet Component

2 Access the definition form for the form object. Right-click with the pointer positioned in the form object (as noted in the table below) and choose Properties from the pop-up menu that is displayed. The form displayed depends on the form object (as listed below) This table shows where to position the pointer and which form is displayed: Form Object Form Field Action Menu Option Popup Menu Option Position the Pointer In form (background) In a field Anywhere In a Menu option In a Popup Menu option Definition Form Form Definition Field in Block Action Definition Menu: Option Definition Popup Menu Definition

For a field, action and menu option object you can double-click the object to access the definition form.

3 Select the Events tab to access the events information. The Events form displays the following fields, enabling you to attach the component (an external handler) to an event:

Instance ID

Interface ID
Function/Method ID

Instance Name

Component Interface Function/Method Name Name Name

4 Select an event for the form object from the Event listbox. 5 Select the component Instance ID that is attached to the event. 6 If the form object attached to the event is an action, attach the event to the action by selecting the number of the action from the Action No. listbox.

40-34

Presentation Components for Forms Utilizing an ActiveX Component

7 To define component (handler) parameters, select the Components tab. Fill in the fields as described in "Creating an Instance for a Form" on page 40-30. If you need to create a new component, click the NewComponent button. 8 Save and exit all forms and close Form Editor.

40.8 Utilizing an ActiveX Component

Preparing the Component
Prepare the component and ensure that it is located at the required address. See Form Reference for information on how to prepare the component.

Defining the ActiveX Component in the Knowledgebase

1 From the Presentation tab of the Navigation Pane of Development Workbench expand Integration and right-click Components:

40-35

40

Presentation Components for Forms Utilizing an ActiveX Component

2 Select Insert ActiveX. The ActiveX (837) form is displayed:

3 Enter a unique identifying number for the component in the ActiveX No. textbox and press <Enter>. 4 Expand the Local knowledgebase node (if unexpanded) to display a list of the ActiveX components defined in the system.

40-36

Presentation Components for Forms Utilizing an ActiveX Component

5 Drag the component to the Business Integrity Server knowledgebase window (left side).

Display the interfaces for the component by expanding the component name. Delete all unnecessary interfaces by right-clicking the interface name and selecting Delete. View the methods for the interfaces remaining by expanding the interface Delete any methods that are not required by right-clicking the method name and choosing Delete.

6 Right-click the component name and select ActiveX Properties:

Use the Add, Edit or Remove buttons to add more properties or to change/delete property values. Click OK to save your changes or Cancel not to save your changes.

40-37

40

Presentation Components for Forms Utilizing an ActiveX Component

7 Right-click the component name and select ActiveX Parameters:

Use the Add, Edit or Remove buttons to add more parameters or a change/delete parameter values. In the Field ID and Field Name textboxes, assign eMerge field numbers and field names to the ActiveX parameters as required. Click OK to save your changes or Cancel not to save your changes.

The component parameters defined here are be used by all component instances. You can, when defining an instance for a component, customize the parameters for the particular component instance (see "Creating an Instance for a Form" on page 40-39). 8 To display any method parameters (a method that has parameters is indicated with the letter p as a subscript on the m symbol), right-click the method name and select Method Parameters:

In the Field textbox, assign eMerge fields to the method parameters as required. Click OK. 9 Click OK to save and exit the ActiveX form.

40-38

Presentation Components for Forms Utilizing an ActiveX Component

Indicating a Component Location ID for a Visible Component

If the component is a visible component, indicate the position and size in the form before creating the instance. Each indication of position and size is identified by a COMPONENT LOCATION ID (GUI ID). 1 Access the form in which you want to place the component and click the Form Editor button. 2 Click the Insert Component button. 3 Place the pointer where you want the component to appear in the form, drag and click. A rectangle appears. Resize the rectangle, if necessary, by dragging the rectangle handles. 4 Click Save, to save the component location information. Note the number shown in square brackets on the status bar. This is the COMPONENT LOCATION ID for the visible component. Record this number for future use. The same COMPONENT LOCATION ID can be used for more than one component or component instance in a form. 5 Save and close Form Editor

Creating an Instance for a Form

The procedure for creating an instance depends on whether the component is visible, whether it includes parameters that are within the HTML specifications for the ActiveX tag, and whether the component instance uses methods. 1 Access the form in which you want to place the component and click the Form Editor button. 2 Right-click in the form and choose Properties from the pop-up menu that is displayed. The Form Definition (10647) form is displayed.

40-39

40

Presentation Components for Forms Utilizing an ActiveX Component

3 Select the Components tab.

4 Enter a unique instance id and an instance name for the component instance int the Instance textboxes. 5 Select ActiveX for the Category. 6 Select the Component ID you want. The Component ID and the Component Name are displayed. 7 For a visible component that is indicated by a COMPONENT LOCATION ID, select the COMPONENT LOCATION ID that was assigned for this instance in the form. See "Indicating a Component Location ID for a Visible Component" on page 40-39. 8 If the component includes properties that are within the HTML specifications for the ActiveX tag and you want to customize the

40-40

Presentation Components for Forms Utilizing an ActiveX Component

parameter definitions for the component instance, click the InitParms button. The initial Parameters (10661) form is displayed:

Enter a name for the property in the Property Name textbox. Select a value for the property from the Value listbox. From the Parameter Field textbox, select the fields that are required as parameters of the instance. Click OK. 9 An instance that is attached to an event, must consist of definitions for methods. If the component instance uses methods, click the Details button to display the Interfaces form:

40-41

40

Presentation Components for Forms Utilizing an ActiveX Component

Select the interfaces that are required for the instance. For each interface, highlight the interface field and click the Methods button. The Methods (813) form is displayed:

Select the methods that are required for the instance. 10 Save and exit all forms and close Form Editor.

40-42

Presentation Components for Forms Utilizing an ActiveX Component

Attaching the Component Instance to an Event

An event controls when a component instance is activated. If a component instance must be activated as long as the form is displayed (not depending on any events), do not perform this procedure. 1 Access the form in which you want to place the component and click the Form Editor button. 2 Access the definition form for the form object. Right-click with the pointer positioned in the form object (as noted in the table below) and choose Properties from the pop-up menu that is displayed. The form displayed depends on the form object (as listed below) This table shows where to position the pointer and which form is displayed: Form Object Form Field Action Menu Option Popup Menu Option Position the Pointer In form (background) In a field Anywhere In a Menu option In a Popup Menu option Definition Form Form Definition Field in Block Action Definition Menu: Option Definition Popup Menu Definition

For a field, action and menu option object you can double-click the object to access the definition form. 3 Select the Events tab to access the events information. The Events tab displays the following fields, enabling you to attach the component (an external handler) to an event:

Instance ID

Interface ID
Function/Method ID

Instance Name

Component Interface Function/Method Name Name Name

40-43

40

Presentation Components for Forms Utilizing an ActiveX Component

4 Select an event for the form object from the Event listbox. 5 Select the component Instance ID that is attached to the event. 6 If the form object attached to the event is an action, attach the event to the action by selecting the number of the action from the Action No. listbox. 7 To define component (handler) parameters, select the Components tab. Fill in the fields as described in "Creating an Instance for a Form" on page 40-39, If you need to create a new component, click the NewComponent button. 8 Save and exit all forms and close Form Editor. 9 Right-click in the component. Select Properties from the pop-up menu that is displayed. The Visible Component Definition (10672) form is displayed:

Select an instance name from the Instance listbox and click OK.

40-44

Chapter 41 Displaying Values on Accessing a Form

Data can be automatically displayed on accessing a form (data form or menu) in any of the following ways:

Existing data is automatically retrieved from the database and displayed. Default values are displayed. See "Defining a Default Value for a Field in a Form" on page 41-7 for details. A value is passed from one form to another form in the flow.

41.1 Displaying Data on Accessing a Data Form

To display data on entry to the form:

1 Using Form Editor, right-click a field in first block.

41-1

41

Displaying Values on Accessing a Form Displaying Data on Accessing a Data Form

2 Choose the Block Properties option from the pop-up menu. The Block form is displayed:

3 Assign the Execute option. 4 Select the Edit operation code in the Operation Code field.

Although it is usually assign on the first block, you can assign Execute any block in the form.

Passing Data Between Forms

Data is passed from one form or menu to another. A field value can be stored in a buffer on exiting one form and retrieved and displayed in another form. Normally data is passed when you choose a menu option or click a form action to access the second form. Data may be passed down the chain from calling form to called form or up the chain from called form to calling form:

41-2

Displaying Values on Accessing a Form Displaying Data on Accessing a Data Form

Passing Data Down the Chain

When data is passed down the chain it can be retrieved and displayed in any form in the chain, and not just the forms called directly from the calling form.

To pass data down a form chain:

1 Display the data form. 2 Using Form Editor, right-click the form and choose Properties from the pop-up menu. The Data Form form is displayed. 3 Click the FormDef button to display the Form Definition form. 4 Access the relevant block in the form definition, that includes the field you want to pass down the chain to a called form. 5 Enter the name of the field whose value is to be stored in the Field Name field. See "Customizing Field Presentation" on page 35-40. 6 Assign the Store option. 7 Display the called form definition (the form where the value must be redisplayed). The called form can be any form accessed from the calling form, either directly or indirectly (i.e. via another form in the chain). 8 Access the relevant block in the form definition, that includes the field you want to redisplay.
41-3

41

Displaying Values on Accessing a Form Displaying Data on Accessing a Data Form

9 Enter the name of the field whose value is to be redisplayed in the Field Name field. 10 Assign the Restore option. When a block has multiple operation occurrences, the value that is stored is the one in the line that the cursor is on in the calling form at the beginning of the flow. If the cursor is not on a line, the value in the first occurrence is stored. For a multiple operation form, and for a field assigned the StoreUp option, when the form is exited, the fields value in the form is stored depending on the placement of the cursor in the form and the following two parameters:

whether the database is Japanese or not whether eMerge is accessed via i.way or 3270 terminal emulation Cursor Placement Non-Japanese Japanese i.way Any field of the form 3270 emulation Any unprotected field Up to two positions from the right most character of the last unprotected field i.way Any field of the operation

3270 emulation Any field of the operation Between the last field and the ending border of the operation

41-4

Displaying Values on Accessing a Form Displaying Data on Accessing a Data Form

Example: For a multiple occurrence form generated when a field is assigned the Store option:

The Employee No. field is assigned two options: Store and StoreUp. For details about the StoreUp option, see "Passing Data Up the Chain" on page 41-6.

41-5

41

Displaying Values on Accessing a Form Displaying Data on Accessing a Data Form

The single occurrence form generated for the concept includes the Restore option:

When the single occurrence form is accessed from the multi-occurrence form (e.g. via the Zoom button) the employee number is displayed. Since the employee number is the key field and the form is set to retrieve data on entry (see "Displaying Data on Accessing a Data Form" on page 41-1), the full employee details are displayed on accessing the form.

Passing Data Up the Chain

When data is passed up the chain (e.g. to return a value selected in a called form), from a called form to a calling form, the data can be retrieved and displayed only in the first form above the called form in the chain, that displays the field. Intermediate forms that do not include the field can be included in the chain.
41-6

Displaying Values on Accessing a Form Defining a Default Value for a Field in a Form

To pass data up a form chain:

1 Access the Form Definition form and display the called form definition. 2 Access the relevant block in the form definition, that includes the field you want to pass up the chain to the calling form. 3 Enter the name of the field whose value is to be stored in the Field Name field. See "Customizing Field Presentation" on page 35-40.

4 Assign the StoreUp option. 5 Display the calling form definition (the form where the value must be redisplayed).

The calling form must be the first form in the chain, above the called form, that displays the field.

6 Access the relevant block in the form definition, that includes the field you want to redisplay. 7 Enter the name of the field whose value is to be redisplayed in the Field Name field. 8 Assign the RestoreFromDown option.

When a block has multiple operation occurrences, the value that is stored is the one in the line that the cursor is on in the called form. If the cursor is not on a line, no value is stored.

41.2 Defining a Default Value for a Field in a Form

You can define a default field value for a field in a form. A default value defined on a field in a form overrides a default value set on the field in an operation or directly on the field in the Field Definition form. In addition you can define a field, used as a sequence number, to automatically be incremented with each occurrence displayed in the form.

To define a default value to a field in a data form:

1 Display the data form.

41-7

41

Displaying Values on Accessing a Form Defining a Default Value for a Field in a Form

2 Using Form Editor, select the required field. Right-click, the following pop-up menu appears:

3 Choose Properties. The Field in Block form is displayed. 4 Click the InitValues button. The Field in Block Initial Values by Language form is displayed:

5 Enter default values for the field in the Initial Value textbox. The default value is displayed depending on the option assigned to the field in the Field in Block form: No option The initial value is displayed on accessing an empty form (the fields do not contain values). EditEmptyInitial The initial value is displayed when retrieving existing data, if the value for the field occurrence is null.

41-8

Displaying Values on Accessing a Form Defining a Default Value for a Field in a Form

EditInitial The initial value is displayed when retrieving existing data, even if there is a database value for the field occurrence. PermanentInitial The initial value is displayed when accessing the form, if the value for the field occurrence is null.

To display occurrences of a field with incremented values:

1 Display the data form. 2 Using Form Editor, select the required field. Right-click, the following pop-up menu appears:

41-9

41

Displaying Values on Accessing a Form Passing Data to and From Menus

3 Choose Properties. The Field in Block form is displayed:

4 Assign the Increment option from the Response subgroupbox. The default starting number is one, and this value is incremented by one for each occurrence.

To change the default starting number and the incrementing value:

1 Position the pointer in the line displaying the field to be incremented. 2 Access the Field in Block form by right-clicking and choosing the Properties option. 3 Click InitValues. The Field in Block Initial Values by Language form is accessed. 4 Enter the default starting value in the Initial Value field. This value is also the value by which the field is incremented.

41.3 Passing Data to and From Menus

If you define a field in a menu (see "Including Data in a Menu via Menu Fields" on page 36-4) you can pass values to and from the field without assigning any options on the field. The store and restore mechanism is automatically implemented.
41-10

Chapter 42 Security for Forms

In order to implement security for a particular form, you can define the forms privacy level. Privacy level determines if a form is confidential (i.e. encrypted) or nonconfidential (i.e. not encrypted) when it is accessed by a web browser client.

SSL 3.0 encryption is supported for form-based privacy level. Form privacy is not supported when working under i.way MDI (Multi Document Interface).

In both cases, the privacy level is inherited by the called forms, i.e. the subsequent forms in the flow. However, you can override the privacy level that a called form inherits.

42-1

42

Security for Forms Defining a Forms Privacy Level

42.1 Defining a Forms Privacy Level

To define a forms privacy level:

1 Using Form Editor, right-click the form background and choose Properties. The Form Definition form is displayed:

2 Define the privacy level in the Privacy Level field (Privacy category). The possible values are: Inherited The privacy level is inherited from the calling formwhether confidential or not. This is the default privacy level for any called form. Nonconfidential The form is not encrypted when it is accessed by a web browser client. This is the default privacy level for any calling form. Confidential The form is encrypted.

42.2 Examples of Privacy Levels

Following are some examples of using privacy levels for forms in an application:

42-2

Security for Forms Examples of Privacy Levels

Nonconfidential
This is the default in which all the forms in the flow are not encrypted. In this case no definitions are required.

Confidential
All the forms in the flow are encrypted. That is, the calling form and all its called forms are encrypted. In this case only one definition is required: the top form is defined confidential (a).

42-3

42

Security for Forms Overriding Default Privacy

Partial Secured
Part of the form flow is encrypted. A particular form in a flow is defined as confidential and this definition is inherited by the forms underneath it in the flow. The privacy level changes when a subsequent form is defined nonconfidential, and this privacy level is inherited by the flow underneath the nonconfidential form. In this case two definitions are required: The first encrypted form is defined confidential (a) and the first nonencrypted form underneath it is defined nonconfidential (b).

42.3 Overriding Default Privacy

You can override the default privacy for any called form. This overrides the privacy level for this form only. Any subsequent forms in the flow are not effected by the change, and retain the privacy level originally defined in the top form.

To override the privacy for a form:

1 Using Form Editor, right-click the form background and choose Properties. The Form Definition form is displayed. 2 Assign the LocalPrivacy option (Privacy category).

42-4

Chapter 43 Form Templates

43.1 What is a Template?

A form template is a model form on which you can base forms. This enables all forms to have the same "look and feel" with minimum effort; i.e. templates can be used to set a standard look for your application. Using templates greatly reduces the number of modifications needed to make to individual forms. They therefore speed up the development process. The work put in to create and define blocks, operations, form actions, color, background, font, etc. can be leveraged from one form to another. If you want all your forms (both default forms and user-defined forms) to use the same template, you may assign a default form template to your concept model. When you create the concept model, all default forms and user-defined forms use the default template assigned to the model (however, you can override the default template and assign another template to any form. See Applying Templates on page 43-10.) In order to assign a default template to a concept model, the template must be defined before creating the concept model. (See Analysis Stage Building a Concept Model on page 2-1.) Each form that has a template assigned starts off with the options you have assigned to the template and objects (See "Dynamic Templates" on page 43-4.) you have defined for the template. You may then modify the individual form where necessary. A template can be dynamic or embedded:

Forms based on a dynamic template have the dynamic template information available to the forms by reference. Any changes made to the dynamic template itself are automatically reflected in the forms. Forms based on an embedded template have the embedded template information copied to the forms. Once a form is based on an embedded template, any changes made to the embedded template itself are not

43-1

43

Form Templates What is a Template?

reflected in the forms (unless the forms are reassigned the embedded template). For example, using dynamic templates you can inherit a look for your forms from more than one dynamic template:

43-2

Form Templates Embedded Templates

43.2 Embedded Templates

The following objects can be added as part of an embedded template:

Actions Components and Events Free Text Images Lines and Rectangles

The default formatting for the following form objects can be set via an embedded template: Form Rectangle Action Field Name Field Value Field Trailer Field with Common Option Field with Protected Option Free Text Top Text Bottom Text
43-3

43

Form Templates Dynamic Templates

Prefix Text Suffix Text Option Text Menu Option Menu Option Button Menu Option Field Table Header (Field Name) Table Column (Field Value) Table

A copy of an embedded template can be an embedded template or a dynamic template.

43.3 Dynamic Templates

The following objects can be added as part of an dynamic template:

Actions Blocks Components and Events Free Text Images Lines and Rectangles

The default formatting for the following form objects can be set via a dynamic template:

Form Rectangle Action Field Name Field Value Field Trailer Field with Common Option Field with Protected Option Free Text Top Text Bottom Text Prefix Text Suffix Text Option Text Table Header (Field Name) Table Column (Field Value)

43-4

Form Templates Defining an Embedded Form Template

Table A dynamic template does not have menu options. A dynamic template cannot be called by another form. A dynamic template can be copied from an embedded template. A copy of a dynamic template is a dynamic template. A dynamic template can be based on another dynamic template: Example: Dynamic template 3002 is based on dynamic template 3001. Form 4000 is based on dynamic templates 3002 and 3001.
dynamic template 3001 dynamic template 3002

Note the following:

form 4000

The block ID and action ID for blocks and actions defined for dynamic templates and for forms that use the dynamic templates must be unique. Therefore, dynamic templates and forms using the dynamic templates cannot have blocks or actions with the same number. Forms or dynamic templates that are based on a dynamic template are automatically assigned the DynamicTemplateInUse option. The Parallel option must be assigned (via the Form Definition form) to a form that is based on a dynamic template.

43.4 Defining an Embedded Form Template

To define a new embedded form template:

1 Right-click Form Templates on the Presentation tab and choose New Template, the Template (100612) form is displayed:

43-5

43

Form Templates Defining an Embedded Form Template

2 Enter the Template No. and Name to identify the template. 3 If the new template is based on an existing template, choose the number of the referred template in the Referred Template field. The Referred Template can only be changed before you click Apply. 4 Assign a Privacy Level (Privacy Category) for the template. The default is Inherited. 5 Assign any options you want to apply. Note that all the options in the Presentation category are automatically assigned to the template. 6 Use the Actions tab to define actions for the template. For details on how to define an action see Chapter 39, Form Actions. 7 Use the Components tab to define components for the template. For details on how to define a component see Chapter 40, Presentation Components for Forms. 8 Use the Events tab to define events that invoke components for the template. For details on how to define an event see Attaching the Component Instance to an Event on page 40-17 9 After making all needed modifications, click the Apply button and then click the Display button to display the template.

43-6

Form Templates Defining an Embedded Form Template

10 Modify the template using Form Editor (See "Types of Forms" on page 34-3.). To modify the default formatting, see below.

To modify the default formatting of the embedded template:

1 Using Form Editor, right-click the template to display the following menu:

Some of the options are for the template as a whole. The Default Formatting option includes the form object types. See "Embedded Templates" on page 43-3. 2 Choose Default Formatting. The Default Formatting form is displayed:

3 Select the form object that you want to change from the Options groupbox (e.g. choose Field Name to change the field names).
43-7

43

Form Templates Defining a Dynamic Form Template

4 Select the specific aspect you want to change from the Description box (e.g. Foreground Color). 5 Click the Change button. The appropriate dialog box opens. Make the changes and click OK. The change is displayed in the Sample groupbox. 6 Repeat steps 2-5 for each form object that you want to change. 7 Click OK for the changes to take effect. Save the changes and exit Form Editor.

43.5 Defining a Dynamic Form Template

To define a new dynamic form template:

1 Right-click Form Templates on the Presentation tab and choose New Dynamic Template. The New Dynamic Template (10624) form is displayed:

2 Enter the Dynamic Template No. and Name to identify the dynamic template.

43-8

Form Templates Defining a Dynamic Form Template

3 If the new dynamic template is based on an existing dynamic template, choose the number of the existing dynamic template from the Dyn. Template in Use drop down listbox. 4 Assign a Privacy Level (Privacy category) for the template. The default is Inherited. 5 Assign any options you want to apply. 6 Use the Blocks tab to define a block for the dynamic template. For details on how to define a block see "Defining a Block" on page 35-4. 7 Use the Actions tab to define actions for the template. For details on how to define an action see Chapter 39, Form Actions. 8 Use the Components tab to define components for the template. For details on how to define a component see Chapter 40, Presentation Components for Forms. 9 Use the Events tab to define events that invoke components for the template. For details on how to define an event see Attaching the Component Instance to an Event on page 40-17. 10 After making all needed modifications, click the Apply button and then click the Display button to display the dynamic template. 11 Modify the template using Form Editor (See "Types of Forms" on page 34-3.). To modify the default formatting, see below.

To modify the default formatting of the dynamic template:

1 Using Form Editor, right-click the template to display the following menu:

Some of the options are for the template as a whole. The Default Formatting option includes the form object types. See "Embedded Templates" on page 43-3. 2 Choose Default Formatting. The Default Formatting form is displayed.
43-9

43

Form Templates Applying Templates

3 Select the form object that you want to change from the Options groupbox (e.g. choose Field Name to change the field names). 4 Select the specific aspect you want to change from the Description box (e.g. Foreground Color). 5 Click the Change button. The appropriate dialog box opens. Make the changes and click OK. The change is displayed in the Sample groupbox. 6 Repeat steps 2-5 for each form object that you want to change. 7 Click OK for the changes to take effect. Save the changes and exit Form Editor.

43.6 Applying Templates

You can apply a template at the following levels during development. Note that each succeeding level overrides the previous level:

Model To a new model. The template is applied to the forms generated when any concept in the model is implemented. To an existing model. The template is applied to the forms generated when any concept in the model is implementedafter this point. Concept To a new concept. The template is applied to the forms generated when the concept (including the main design) is implemented. To any additional designs defined for a concept. The template is applied to the forms generated when the design is implemented. Form To a new form. The template is applied to the newly defined form. To an existing form. The template for an existing form can be changed only if there are no graphical interface definitions for the form. If needed, the graphical interface definitions can be deleted.

The following sections describe how to apply a template to each of the above levels.

Applying a Template to a New Concept Model

You may apply a template to each new model you insert. When you do this, all forms generated when a concept in the model is implemented use the specified template.

43-10

Form Templates Applying Templates

To apply a template to a new concept model:

1 Right-click Models on the Data tab.

2 Choose New Model. The New Concept Model form is displayed:

3 Fill in the model information. For more information see "Inserting a New Concept Model" on page 2-2. 4 Select the number of the template you want from the Forms Template field. All forms generated when a concept in the model is implemented have the selected template assigned to them.

Applying a Template to an Existing Model

You may change the template for an existing model. However, this only changes the template for forms generated after the change (by concepts implemented after that point). Any concepts that have already been defined continue to use the old template.

To apply a template to an existing model:

1 Open the model.

43-11

43

Form Templates Applying Templates

2 Choose ModelProperties. The Concept Model Details form is displayed:

3 Select the number of the template you want from the Forms Template field. All forms generated after this point, when any concept in the model is implemented, have the selected template assigned to them, by default.

You can override the template used for a particular concept or a particular form.

Applying a Template to a New Concept

To use a different template for a particular concept in a model (as opposed to the template applied to the model), you can assign a template to that concept. This must be done at the analysis or design stage. The main design is assigned the template given to the concept. The template for the main design cannot be changed.

43-12

Form Templates Applying Templates

To apply a template to the main design of a concept:

1 Select a concept and click the Fields button. The Concept form is displayed:

2 Select the number of the template you want from the Template field. All forms generated when the concept in the model is implemented have the selected template assigned to them.

Applying a Template to an Additional Design

For any additional designs, a different template may be assigned than the one assigned to the main design. Even if the concept is implemented, when you add a new design, the template can be changed for the new design.

To apply a template to a new additional design:

1 Right-click the concept and choose ObjectConcept Design. The Concept: Design form is displayed:

43-13

43

Form Templates Applying Templates

43-14

Form Templates Applying Templates

2 Right-click the Design field and choose New Design on the popup menu. The Concept: New Design form is displayed:

3 Fill in the form. See "Creating a New Design" on page 4-12 for more information. Do not as yet assign Implementation. 4 Click the Advanced button. The Design Advanced form is displayed: 5 Select the number of the template you want from the Forms Template field. All forms generated when the design is implemented have the selected template assigned to them. 6 Click Apply and then Exit. The Concept: New Design form is redisplayed. 7 Assign Implementation.

43-15

43

Form Templates Applying Templates

Applying a Template to a New Form

A template may be applied to a new form that overrides the template assigned to the model or concept or particular design.

To apply a template to a new form:

1 Right-click the concept and choose ObjectConcept Design. The Concept: Design form for the concept is displayed.

2 Right-click the Design field and choose Design Objects > Forms on the popup menu. The Constructor Forms form is displayed:

3 Fill in the form. See Defining a Data Form on page 35-2 for more information. 4 Choose the number of a template from the Template field. The selected template is assigned to the new form. 5 If the template selected is a dynamic template, assign the Parallel option to the form. 6 Display and customize the form using Form Editor.

Applying the Template for an Existing Form

You can change the template applied to an existing form, or apply a template to a form that does not have a template applied.
43-16

Form Templates Applying Templates

To apply a template to an existing form:

1 If the form already has a template assigned or any GUI definitions, it can only be changed after all the graphical interface definitions for the form are deleted. Using Form Editor, right-click the form and choose Reset Form > All. 2 Using Form Editor, right-click the form and choose Properties. The Form Definition form is displayed:

3 Select the template you want from the Template field. 4 If the template selected is a dynamic template, assign the Parallel option.

43-17

43

Form Templates Applying Templates

43-18

Chapter 44 Form Components

44.1 What is a Form Component

Form components enable:

A form flow that goes from one module to another modulelinking a form in one module with a form in another module. Defining a top form for a user.

44.2 Flows Across Modules

A form (i.e. the calling form) in one module (i.e. the source module) can be linked to a form (i.e. the called form) in another module (i.e. the target module). The end user "goes" from the calling form to the called form via any of the usual ways of invoking a form by another form, including a select form, a form action, or a popup menu. Example: The WT_ORDER_SELECT form in the figure below is defined in the WT module. The values that can be selected in the WI Customer Id field come from a select form in the WB module.

44-1

44

Form Components Flows Across Modules

Clicking the Customer form action on the WT_ORDER_SELECT form opens the WB_CUSTOMER form in the WB module:

The following is the overall procedure. The Linking a Form from One Module to a Form in Another Module section below describes the procedure in detail.

44-2

Form Components Flows Across Modules

To link a form from one module to a form in another module:

1 Ensure that both modules are in the same application.

2 Note the form numbers for the calling form and for the called form and any values that may have to be moved between the forms. 3 Define a package. 4 Define any needed domains. 5 Define a form component in the package. The form component is used to link the two modules. 6 Define, if needed, Return fields (on the Properties tab page of the Form Component Definition form) for values that are to be "brought back" to the calling form from the called form. Domains are selected for each return field; e.g. Numeric 2.

44-3

44

Form Components Linking a Form from One Module to a Form in Another Module

7 Define, if needed, Input parameters (on the Call Method tab page of the Form Component Definition form) for values that are to be "brought to" the called form from the calling form. Types are selected for each input parameter; e.g. Decimal, Date. 8 Define a proxy form in the source modulethe module with the calling form. 9 Define a stub form in the target modulethe module with the called form.

44.3 Linking a Form from One Module to a Form in Another Module

1 Access Development Workbench as a developer. The Component Integration tab is displayed in the navigation pane.

44-4

Form Components Linking a Form from One Module to a Form in Another Module

2 Expand the Package node and choose New Package. The Package Definition form is displayed:

3 Define a package where the provider module is the module that contains the called form: 1. Enter a name for the package in the Package textbox. The package name can only contain alphanumeric characters (it cannot contain any blanks or any non-alphanumeric characters, i.e. it cannot contain any special characters, e.g. # < $ % ^ & * ...). A package name can be up to 78 characters. The first character of the package must be lower case. The package is initially assigned a Status of Development (after you click Apply or OK). 2. Specify a module in the Providers tabpage. The provider module is the module that contains the called form. 3. Click OK to save the definition. The new package name is displayed
44-5

44

Form Components Linking a Form from One Module to a Form in Another Module

under the BC Packages node.

The same package can be used for both Business Components and for form components. However, you may want to separate the components for convenience.

4 Expand the BC Packages node and right-click the package to be used and choose New Form Component. The Form Component Definition form is displayed:

5 Enter the name of the form component. 6 In the Properties tabpage, enter names for the return fieldsthat is, the values that are to be brought back to the calling form, if necessary, and select the domain needed for each field (e.g. SYSNumeric2). See "Defining Domains" on page 44-10. 7 In the Call Method tabpage, enter a name for any input parametersthat is, the values that are to be taken over to the called form, if necessary, and select a value from the Type listbox (i.e. Long, Decimal, Date, String). 8 Click OK.
44-6

Form Components Linking a Form from One Module to a Form in Another Module

9 Select the calling module from the Module Selector box, located at the top of the navigation pane. The entry point for the developer of the calling module is displayed:

10 If you need input parameters (values to take from the calling form) and/or return fields (i.e. values to take from the called form), ensure there is an operation that contains the fields. Note the fields are all fields in the calling form (in the calling module). 11 From the Presentation tab, right-click the Proxy/Stub Forms node, and choose New Proxy Form. The Proxy Form Definition form is displayed:

44-7

44

Form Components Linking a Form from One Module to a Form in Another Module

12 Enter a form number and name for the proxy form. 13 Select the form component (that was defined in Step 4). 14 If you need input parameters (i.e. values to take from the calling form) and/or return fields (i.e. values to take from the called form), enter a block number and select the number and name of the operation defined in Step 10. 15 Select the fields in the Field field that belong to the operation. For each field, select an input parameter or a return field from the form component. 16 Click OK. 17 From the Module Selector box, select the module that contains the called form. 18 From the Presentation tab, right-click the Proxy/Stub Forms node and choose New Stub Form. The Stub Form Definition form is displayed:

44-8

Form Components Linking a Form from One Module to a Form in Another Module

19 Enter the form number and name for the stub form. 20 Select the form component that was defined in step 5. 21 Enter the form number of the called form in the Display Form field. 22 If you need input parameters (i.e. values to take from the calling form) and/or return fields (i.e. values to take from the called form), enter a block number and select the number and name of the operation defined in Step 10. 23 Select the fields from the Field field that belong to the operation. For each field, select an input parameter or a return field from the form component. 24 Click OK.

44-9

44

Form Components Defining Domains

44.4 Defining Domains

A domain contains the characteristics for a component property field. It is similar to the field definition for an eMerge field. Each component property must have a domain definition. A set of default domains is supplied by the system. If necessary, you can define your own customized domains.

To define a domain

1 Access Development Workbench as a developer. The Component Integration tab is displayed in the navigation pane:

2 From the Component Integration tab, right-click Domains and choose New Domain. The Domain Definition form is displayed:

44-10

Form Components Defining Domains

3 Enter a name for the domain in the Domain textbox. 4 Select a data type for the domain from the Type listbox. Numeric Numeric, Binary, PackedDecimal and ZonedDecimal. Positive numbers, zero, including decimal points: NotZero A value of Zero is not allowed (the default is zero and positive values) MayBeNegative Character Negative values are allowed.

(Character, Fixed and Variable) The value specified for the Field Size of a character field determines the internal representation of the character field; fixed or variable:

A Field Size less than 17 results in a fixed length character field. A Field Size greater than 16 results in a variable length character field. A Field Size greater than 78 results in a long variable length character field (maximum size is 32000).

Character Fields: AlphaNumeric Letters, blanks, numbers, " . - _ # AlphaBetic Mixed Letters, blanks, " . - _

Both upper and lower case characters are allowed. Relate to second language fields.

SecondLanguage and SCL-Mixed Date Must be a valid date.

Change these default values by assigning options or defining a domain of possible values. Defining Date Fields Define a date field by specifying a value of Date in the Data Type field. The date format can be year, month-year or daymonth-year. It is determined by the value in the Size field as shown in the following table: Size Field 2 4 5a yy yyyy mm.yy European Format yy yyyy mm.yy
44-11

American Format

44

Form Components Defining Domains

Size Field 6a 7 8 9 10 11
a

European Format mon yy mm.yyyy dd.mm.yy dd mon yy dd.mm.yyyy dd mon yyyy

American Format mon yy mm.yyyy mm.dd.yy mon dd yy mm.dd.yyyy mon dd yyyy

Cannot be used in computations.

yy is a two-digit year and yyyy is a four-digit year. mm is the month represented by a number while mon is the month represented by a three letter month code. dd is the day. The default separator for date formats that include mm is . (i.e. a period). The default separator for date formats that include mon is a blank. The minimum value for the year in a date field is 1900. The maximum is 2898.

Use the DATESEP command to change the default separators. See General Reference.

The Administrator can change the default date format from the European convention (day-month-year) to the American convention (month-day-year) or to a reversed format (year-month-day). See the Business Integrity Server Administration Reference. 5 Enter a size for the data type in the Size textbox. 6 Optionally, specify possible values for the domain:

Specify values and/or ranges of values that describe valid data for the component properties to which this domain applies. For a distinct value: Enter a value in the Low Value field to specify the lower limit for a range, one value per occurrence. For a range of values: Enter values by specifying the lower end of the range in the Low Value field and the upper end of the range in the High Value field. Values may be alphabetical or numeric, depending on the data type of the field. Use the Value Meaning property field (Description category) to describe a value or a range. You must enter a value in the Value Meaning field.

44-12

Form Components Defining a Top Form for a User

Value Meaning is a multilingual language field. If you are working in dual language mode or multilingual mode, the first character of the field value must be the Language short code. For example, the E character identifies the language of the meanings as English. 7 To specify (mixed case letters) for meaning and explanation by language for a domain, click Language. The Value: Meanings and Explanations by Language form is displayed:

1 Select a language from the Language listbox. 2 Specify a meaning for the value in the Meaning textbox. 3 Specify an explanation for the value in the Explanation textbox. 4 Click OK.

44.5 Defining a Top Form for a User

1 Access Development Workbench as a developer. The Component Integration tab is displayed in the navigation pane.

44-13

44

Form Components Defining a Top Form for a User

2 Expand the Package node and choose New Package. The Package Definition form is displayed:

3 Define a package where the provider module is the module that contains the called form: 1. Enter a name for the package in the Package textbox. The package name can only contain alphanumeric characters (it cannot contain any blanks or any non-alphanumeric characters, i.e. it cannot contain any special characters, e.g. # < $ % ^ & * ...). A package name can be up to 78 characters. The first character of the package must be lower case. The package is initially assigned a Status of Development (after you click Apply or OK). 2. Specify a module in the Providers tabpage. The provider module is the module that contains the top form. 3. Click OK to save the definition. The new package name is displayed
44-14

Form Components Defining a Top Form for a User

under the BC Packages node.

The same package can be used for both Business Components and for form components. However, you may want to separate the components for convenience.

4 Expand the BC Packages node and right-click the package to be used and choose New Form Component. The Form Component Definition form is displayed:

5 Enter the name of the form component. 6 Click OK. 7 From the Module Selector box, select the module that contains the top form. 8 From the Presentation tab, right-click the Proxy/Stub Forms node and choose New Stub Form. The Stub Form Definition form is displayed:

44-15

44

Form Components Defining a Top Form for a User

9 Enter the form number and name for the stub form. 10 Select the form component that was defined in step 5. 11 Enter the form number of the top form in the Display Form field.

44-16

Part F

Help for Applications

Chapter 45 Documentation and Help Text for Applications

Documentation text can be entered for knowledgebase objects. The text is entered and viewed by the application developer, to provide a description of the object, and any other information. Documentation provided for fields can be accessed as help text by the end user.

45.1 Documenting Knowledgebase Objects

These types of knowledgebase objects have documentation forms. Action Block Class Composite Concept Constructor Field Field in Block Field in Class Field in Operation Field Value Form/Menu Job Menu Option Operation Program Query Rule Ruleset Value

For most knowledgebase objects, there are also documentation forms for entering documentation text for a second language and for additional languages. For each type of object, the documentation form is accessed from the definition form by clicking the Document button:

45-1

45

Documentation and Help Text for Applications End User Help Text for Fields

45.2 End User Help Text for Fields

Documentation provided for fields can be accessed by the end user by clicking the Help button on the toolbar when the insertion point is on a particular field. This means that care must be taken to ensure that field documentation is correct and attractive. It should not contain any information that you do not want the end user to view.

Defining Help Text for a Field

1 In the model, select an object that has fields and click the Fields button to access the Concept form.
45-2

Documentation and Help Text for Applications End User Help Text for Fields

2 With the insertion point on the definition of the field for which you want to provide documentation, click FieldDef to access the Field Definition form. 3 Click the Document button to access the Field Documentation form.

4 Enter documentation text. To advance to a new line, press <Shift>+<Enter>. 5 If necessary, click the SecondLang or Language button to enter documentation in another language.

Displaying a Blank Line in Help Text

Every line entered into the Documentation text box must contain text. To provide spacing between lines in the help text displayed to the end user, put a place holder character at the beginning of each line. For example:
! ! ! ! ! First line of text. Next line of text, following a blank line.

Displaying the Fields Possible Values in its Help Text

For a field that has possible values defined for it, use the .include values command to include the list of possible values in the help text:

45-3

45

Documentation and Help Text for Applications End User Help Text for Fields

.include values

The .include values command must appear on its own line.

Example of Help Text Formatting

The following documentation is provided for a field that has possible values defined.

When the end user clicks the help button on the toolbar, the following help is displayed:

45-4

Part G

Reports and Queries

Chapter 46 Reporting

Use the following to produce reports in eMerge:

Listings (via retrieval operation codes) Information Tools eMerge query language DBCOBOL and DBPL1 languages (on platforms that support these languages)

Each of these can be used both online and in batch with no significant difference in development. Listings, Development Tools, queries, DBCOBOL and DBPL1 can generate output for the printer, to a data entry form, to a listing form, or to disk. All of these methods make full use of all eMerge facilities, including data and presentation rules, the knowledgebase, and security.

46.1 Listings
A listing, via one of the retrieval operation codes (A, B, E, F, L and M), is the most basic way of creating a report in eMerge. Each retrieval code produces a specific type of report. For details, refer to "Basic Reports via Retrieval Operation Codes" on page 47-1.

46.2 Information Tools

Information tools are a set of menu-driven utilities that can be used by the developer to search an application for rules, queries, error messages or BLP commands that meet the specified search criteria. They are described in Chapter 48, Information Tools.

46-1

46

Reporting Querying and Manipulating Data

46.3 Querying and Manipulating Data

A query is a request for information, and a set of instructions on how to format and display that information. Use queries for the following:

Produce simple reports, including statistical functions (averages etc.). Copy data to an external file, based on specific criteria. Update the database, based on specific criteria.

46.4 Querying Temporary Composites

Temporary composites are composites that exist temporarily in task memory and are not stored on a physical database. A temporary composite in task memory behaves vis-a-vis queries the same as a composite stored on a physical database. Queries can request information, generate reports, and perform searches on temporary composite data. When a query/program uses a temporary composite, a ruleset triggered by the query can populate the temporary composite (when ImmediateExecution is assigned). The query/program uses data populated by the ruleset.

46.5 Complex Reporting and Data Manipulation

In environments that support them, use DBCOBOL and DBPL1 for complex reporting and data manipulation. DBCOBOL and DBPL1 are 4GL extensions to COBOL and PL/I to allow COBOL or PL/I programs to access and update the eMerge database. These programs can be executed either online from within eMerge, or in batch mode externally. For more information, consult the DBCOBOL Guide or the DBPL1 Guide.

46-2

Chapter 47 Basic Reports via Retrieval Operation Codes

You can generate basic reports using retrieval operation codes (Retrieve All, Basic List, Extract, Full Retrieval, List, Main List).

47.1 Operation Codes

List of Operation Codes
The different operation codes produce different listings: retrieve all
A Lists all fields defined in the operation for all the occurrences of the target class, from the field number specified, or from the first field if no number is specified. If a key value is entered the listing starts from this value. B

basic list

Lists all fields defined in the target class for all its occurrences, from the field number specified, or from the first field if no number is specified. If a key value is entered the listing starts from this value.

extract

E Lists all fields in the operation for one occurrence of the target class whose key is specified in the operation. Displays the operation on an eMerge form. The operation code changes to C (change), allowing you to change the data. When in an only edit session, the blank (default) character in the Operation Code field is treated as edit mode. F Lists all fields in the target class for one occurrence whose key is specified in the operation. L Lists all fields in the target class for all occurrences, including all dependent classes of the target class, from the field number specified, or from the first field if no number is specified. If a key value is entered the listing starts from this value.

full retrieval list

47-1

47

Basic Reports via Retrieval Operation Codes Showing the Listing as a Report

main list

M Lists all fields in the target class for one occurrence whose key is specified in the operation, including all dependent classes of the target class.

Using Retrieval Operation Codes

The following chart shows which retrieval operation code to use with which data structure (operation or class) and what is displayed (only the data for the key or the data for a range). Operation Key All
a

Class F B M L

Class & Dependents

E A

If a key value is entered the listing starts from this value.

47.2 Showing the Listing as a Report

You can format a listing so that it is produced as a report. When you request a listing (e.g. via a listing command such as 600,m,330000), the listing output is displayed in a Listing window. You can print the active listing window by clicking the Print button.

Right-click in the Listing window and selecting Print from the pop-up menu that is displayed.

47-2

Basic Reports via Retrieval Operation Codes Changing a Field Name Displayed in a Listing

A listing when displayed within Development Workbench can be saved. The default file name is listing.txt. The default directory is <emergeclient>\listing.

To format a listing as a report:

1 Type the listing command text into the Execute Command box of Development Workbench:

2 Press <Enter> to execute the command and view the listing.

47.3 Changing a Field Name Displayed in a Listing

Usually, the name that is displayed for a field is the name defined for the field in the Concept form. The name can be changed for all listings requested as a report. 1 From Modeler, right-click the Concept and select Object>Concept Design from the pop-up menu that is displayed. The Concept Design form is displayed. Select a field whose name you want to change and right-click

47-3

47

Basic Reports via Retrieval Operation Codes Listing Additional Information

in the field. Select Detail from the pop-up menu that is displayed. The Field Definition form is displayed:

2 Enter the name you want in place of the field name in the English textbox (Titles category).

The name change applies to the field in all listing reports.

47.4 Listing Additional Information

If additional information exists for data in a listing (e.g. meaning fields for hexadecimal options) this data can be included in the listing. 1 Type decode all into the Execute Command box:

2 Press <Enter> to execute the command.

Return to the default, basic listing, by issuing the DECODE OFF command.

47-4

Chapter 48 Information Tools

Information tools are a set of menu-driven utilities that can be used by the developer to search an application for knowledgebase objects (e.g. rules, queries, error messages, BLP commands) that meet specified search criteria. The output destination for the search results can be a form or a report. A search can be performed for information for any of the following: Field Class Composite Operation Form Specific information in the field definition in a specific field range, including fields by field or field data type and/or size. Specific information in the class definition in a specific class range. Specific information in the composite definition in a specific composite range. Specific information in the operation definition in a specific operation range. Specific information in the form definition in a specific form range and BLP command in private commands menu options or in entry/exit commands. Specific information in the field in form definition in a specific form range. Specific information in the ruleset definition in a specific ruleset range. Rules or rulesets meeting the following criteria:

Field in Form Ruleset Rule

rules assigned Inactive non-attached rulesets rules not assigned SameComposite (that may need it) rules with a particular string, option, target, or field

Query

Queries with a specific string or subject composite. You can search for queries performing sequential scans, multiple scans, or multiple accesses, so you can check if they need to be updated to improve performance.

48-1

48

Information Tools How To Search

Error DBMS Adapter

Error messages that contain a specific string. Information about the mapping to an external database. The search tools can also be run in batch mode. See "Using the Search Tools in Batch" on page 48-10.

48.1 How To Search

A search is initiated from the Information Tools option located on the Tools tab of the Navigation Pane of Development Workbench.

Selecting a Topic to Search

1 From the Tools tab right-click InformationTools, the following menu appears:

2 Choose an option to search. Depending on the option chosen, a search form containing information specific to that option is accessed. Search results can be displayed on an output form or in a report. From the form you can link to the relevant definition form.

48-2

Information Tools Searching for Rulesets

Range for the Search

A search for any of the knowledgebase objects listed above requires a range to search. For example, you search for rulesets from a given number to a given number. eMerge filters the search range, selecting only ranges that are appropriate to search for the particular knowledgebase object. Therefore, you can give a range to search that seems appropriate, and if some parts of the range given are not relevant to the user, eMerge filters it out. This results in a more efficient search being performed.

Selecting an Output Destination for the Search Results

The output destination for the search results is specified via the search tool form. 1 Double-click the Output field on any of the search tool forms. A listing of possible output destinations is displayed. 2 Choose an output destination from the possible values:
TO REPORT

You get a listing output.

TO FORM You get a form listing the results. The form is specific to the type of search result requested.

From the output form, you can access the definition form for the particular search topic you selected (the ruleset definition form to see the ruleset definition, the rule definition form to see the statements for a rule, the query definition form to see the query text, the error definition form to see the error text, etc.).

Accessing a Search Topic Definition Form via the Output Form

1 Click on an item listed on the output form for which you want to see the definition. 2 Right-click the item. Select Detail from the pop-up menu that is displayed. The appropriate definition form is displayed.

48.2 Searching for Rulesets

You can search for rulesets meeting the following criteria:

48-3

48

Information Tools Searching for Rules

non-attached rulesetsrulesets that are not connected to any of the following: classes, forms, operations, edit operations, programs, queries or errors inactive trigger rulesetsrulesets that are inactive rulesets without a nameunnamed rulesets

To search a specific ruleset range matching your criteria:

1 From the Tools tab, right-click Information Tools and choose Ruleset Tools. The Ruleset Information Tools menu is accessed:

2 Enter the range of ruleset numbers to search in the Ruleset Range textboxes. 3 Enter the output destination in the Output textbox. Right-click with the pointer in the Output textbox and choose Select from the pop-up menu that is displayed. Choose an output destination. 4 Select the appropriate ruleset search menu option.

48.3 Searching for Rules

You can search for rules meeting the following criteria: rules where the rule source and target composites are the same, but the rule has been defined without the SameComposite option

48-4

Information Tools Searching for Rules

rules with a particular string, option, target, or field value rules with the Inactive option rules with trace onrules that have the trace on option assigned. rules without rule statementsrules that do not contain rule statements rules by target optionrules having particular target options assigned rules having a containing a particular target name rules without error messagesrules that do not contain a reference to an error message rules by optionsrules that have particular options assigned

To search a specific rule range matching your criteria:

1 From the Tools tab, right-click Information Tools and choose Rule Tools. The Rule Information Tools menu is accessed:

2 Choose an output destination. With the pointer in the Output textbox click the Select button and choose an output destination. 3 Choose how to display the font characters (upper or mixed character sizes). Right-click with the pointer in the Case textbox and choose Select
48-5

48

Information Tools Searching for Rules

from the pop-up menu that is displayed. Choose one of the possible values for the Case parameter. 4 Select the appropriate rule search menu option. Some of the options access additional forms: If you choose the Target in Rules option, the Rules Target Information form opens, and you must supply additional search criteria and choose one of the target options:

If you choose the Performance Information option, the Performance Information form opens, and you must supply additional search criteria and choose one of the performance options:

You receive a list of all rules in the specified ruleset range that match your search criteria.

48-6

Information Tools Searching for Queries

48.4 Searching for Queries

You can search for queries with a specific string or subject composite. You can search for queries performing sequential scans, multiple scans, or multiple accesses, to check if they need to be updated to improve performance. 1 From the Tools tab right-click Information Tools and choose Query Tools. The Query Information Tools menu is accessed:

2 Enter numbers for the range of queries to search in the Query Range textboxes of interest to you, and any information required by the option you need. 3 Choose an output destination. Right-click with the pointer in the Output textbox and choose Select from the pop-up menu that is displayed. Choose an output destination. 4 Choose how to display the characters (upper or mixed character sizes). Right-click with the pointer in the Case textbox and choose Select from the pop-up menu that is displayed. Choose one of the possible values for the Case parameter. 5 Select the query search menu option you want.

48-7

48

Information Tools Searching for Error Text

48.5 Searching for Error Text

You can search for specific text in first language or second language error messages, in a specified error range. You can search for specific text in first language or second language rule error messages, in a specified ruleset range. 1 From the Tools tab right-click InformationTools and choose Error Tools. The Error Information Tools menu is accessed:

2 Enter the string for which you want to search in the String textbox. 3 Choose an output destination. Right-click with the pointer in the Output textbox and choose Select from the pop-up menu that is displayed. Choose an output destination. 4 Choose how to display the font characters (upper or mixed character sizes). Right-click with the pointer in the Case textbox and choose Select from the pop-up menu that is displayed. Choose one of the possible values for the Case parameter. 5 Enter the range of errors or rules to search in the appropriate From Error, To Error or From Ruleset, To Ruleset textboxes.

48-8

Information Tools Searching for BLP Commands

6 Select the error search menu option you want.

48.6 Searching for BLP Commands

You can search for a specific BLP command in private commands, menu options, or in entry/exit commands.

To search a specific range of forms for BLP commands matching your criteria:

1 From the Tools tab right-click Information Tools and choose Form Tools. The Form Information Tools menu is accessed:

48-9

48

Information Tools Using the Search Tools in Batch

2 Choose the BLP Commands in Form option. The BLP Command Information form is accessed:

3 Enter the BLP command for which you want to search in the BLP Command textbox. 4 Choose an output destination. Right-click with the pointer in the Output textbox and choose Select from the pop-up menu that is displayed. Choose an output destination. 5 Enter the form range to search in the appropriate From form, To form textboxes. 6 Select the search menu option you want.

48.7 Using the Search Tools in Batch

The queries run by the search tool utilities can be run in batch mode. You must pass the same parameters that are needed when you run the queries from the menus. Output is in report format. Query Number 160 162 164 166
48-10

Field Information Queries

ERRORS IN FIELD DEFINITION SELECT & DETAIL FOR NON SUBJECT SELECT & DETAIL FOR SUBJECT POSSIBLE VALUES WITHOUT DECODE

Parameters from field, to field, output type from field, to field, output type from field, to field, output type from field, to field, output type

Information Tools Using the Search Tools in Batch

Query Number 168 170 172 174 176 178 180 182

Field Information Queries

FIELDS WITH NAME ATTR STRING IN FIELD NAMES STRING IN FIELD SCL NAMES STRING IN FIELD TITLES STRING IN FIELD SCL TITLES STRING IN FIELD SYNONYMS STRING IN FIELD SCL SYNONYMS ALL FIELDS BY ATTRIBUTES

Parameters from field, to field, output type string, output type, from field, to field string, output type, from field, to field string, output type, from field, to field string, output type, from field, to field string, output type, from field, to field string, output type, from field, to field from field, to field, output type, checkset-A, checkset-B

Query Field In Form Information Queries Number 660 666 668 670 678 692 694
STORE-RESTORE INCONSISTENCE RESTORE OF FIELDS WITH E & EXEC RESTORE FIELDS WITH LEN IN FORM MULTY OCC OF FLD IN BLOCK ALL FLDS IN BLOCK BY ATTRIBUTES STRING IN FIELD NAMES IN FORMS STRING IN FIELD SCL NAMES IN FORMS

Parameters from form, to form, output type, case from form, to form, output type, case from form, to form, output type, case from form, to form, output type, case from form, to form, output type, case, checkset-A, checkset-B from form, to form, output type, case, string from form, to form, output type, case, string

Query Number 250 252 254 256 258 260

Class Information Queries

KEY LENGTHS SEGMENT WITHOUT RECORDS SEGMENT WITHOUT TRANSACTIONS TOTAL FLD LEN IN SEG STRING WITH SEGMENT NAMES STRING IN SEGMENT SCL NAMES

Parameters from class, to class, output type from class, to class, output type from class, to class, output type from class, to class, output type from class, to class, output type, string from class, to class, output type, string

48-11

48

Information Tools Using the Search Tools in Batch

Query Number 262 264 266 268

Class Information Queries

STRING IN SEGMENT SYNONYM STRING IN SEGMENT SCL SYNONYM ALL SEGMENTS BY ATTRIBUTE ALL FLD IN SEG BY ATTRIBUTES

Parameters from class, to class, output type, string from class, to class, output type, string from class, to class, output type, checkset from class, to class, output type, checkset-A, checkset-B

Query Number 275 277 279 281

Composite Information Queries

ALL RECORDS BY ATTRIBUTES RECORDS WITHOUT SEGMENTS STRING IN RECORD NAMES STRING IN RECORD SCL NAMES

Parameters from composite, to composite, output type, attribute from composite, to composite, output type from composite, to composite, output type, string from composite, to composite, output type, string

Query Number 444 484 486 488 490 492 494 496

Operation Information Queries

UNUSED TRANSACTIONS TRANS WITHOUT TARGET TRANSACTION LENGTH STRING IN TRANS NAME STRING IN TRANS SCL NAMES STRING IN TRANS SYNONYM STRING IN TRANS SCL SYNONYM ALL TRANS BY ATTRIBUTE

Parameters from operation, to operation, output type from operation, to operation, output type from operation, to operation, output type from operation, to operation, output type from operation, to operation, output type, string from operation, to operation, output type, string from operation, to operation, output type, string from operation, to operation, output type, checkset

48-12

Information Tools Using the Search Tools in Batch

Query Number 498 500

Operation Information Queries

ALL TRANS BY TARGET ATTRIBUTE ALL FLD IN TRANS BY ATTRIBUTES

Parameters from operation, to operation, output type, checkset from operation, to operation, output type, checkset-A, checkset-B

Query Number 662 664 674 676 684 686 688 690

Form Information Queries

PROBABLY UNUSED FORMS COMPLICATED SCREEN FORMS ALL FORMS BY ATTRIBUTE ALL BLOCKS BY ATTRIBUTES STRING IN MENU LINE STRING IN SCL MENU LINE STRING IN FORM NAMES STRING IN FORM SCL NAMES

Parameters from form, to form, output type, case from form, to form, output type, case from form, to form, output type, case, checkset-A, checkset-B from form, to form, output type, case, checkset-A, checkset-B from form, to form, output type, case, string from form, to form, output type, case, string from form, to form, output type, case, string from form, to form, output type, case, string

Query Number 680 682 683 681

Image Information Queries

ALL FORMS WITH IMAGES ALL BLOCKS WITH IMAGES ALL MENU LINES WITH IMAGES ALL BUTTONS WITH IMAGES

Parameters image, output type, from form, to form image, output type, from form, to form image, output type, from form, to form image, output type, from form, to form

Query Number 702 704

Ruleset Information Queries

INACTIVE TRIGGERS PROCESS WITHOUT NAME

Parameters from ruleset, to ruleset, output type from ruleset, to ruleset, output type

48-13

48

Information Tools Using the Search Tools in Batch

Query Number 736 Query Number 714 716 764 765 752 761 767 769 771 770 766 768

Performance Improvement Information Queries

RULES WITHOUT FETCH INMEM

Parameters from ruleset, to ruleset, output type Parameters from ruleset, to ruleset, output type, case from ruleset, to ruleset, output type, case from ruleset number, to ruleset number from ruleset number, to ruleset number from ruleset number, to ruleset number from ruleset number, to ruleset number, string from ruleset number, to ruleset number, checkset-A, checkset-B, checkset-C from ruleset number, to ruleset number, checkset-A, checkset-B from ruleset number, to ruleset number, object name from ruleset number, to ruleset number, constructor number from ruleset number, to ruleset number, class number, composite number from ruleset number, to ruleset number, field number, value

Rule Information Queries

RULES WITH SOURCE CHECK RULES WITHOUT TOL STATEMENTS ALL INACTIVE RULES ALL NON-ATTACHED PROCESSES ALL RULES WITHOUT SAMEREC STRING IN TOL ALL RULES BY ATTRIBUTES RULES BY TARGET ATTRIBUTESS TARGET OBJECT IN RULES TARGET SEGMENT IN RULES TARGET SEGMENT IN RULES ALL RULES FOR FIELD WITH VALUE

Query Number 706 708

Target In Rule Information Queries

FETCH-DERIVE WITHOUT TARGET RULES WITH NON EXIST TARGET

Parameters from ruleset, to ruleset, output type, type from ruleset, to ruleset, output type, type

48-14

Information Tools Using the Search Tools in Batch

Query Number 239 154 151 152 153 810 812

Query Information Queries

STRING IN QUERY QUERIES FOR SUBJECT RECORD QUERIES WITH SEQUENTIAL SCAN QUERIES WITH MULTIPLE SEQ SCANS QUERIES WITH MULTIPLE ACCESS QUERIES WITHOUT STATEMENTS QUERIES WITH FORM & SORT

Parameters from query number, to query number, string from query number, to query number, subject composite number from query number, to query number from query number, to query number from query number, to query number from query, to query, output type, case from query, to query, output type, case

Query Number 1051 1052 710 712 762 763

Error Information Queries

STRING IN ERRORS STRING IN SCL ERRORS STRING IN RULE WARNINGS STRING IN RULE SCL WARNINGS STRING IN RULE ERRORS STRING IN RULE SCL ERRORS

Parameters string, from error number, to error number string, from error number, to error number string, output type, case, from ruleset, to ruleset string, output type, case, from ruleset, to ruleset string, from ruleset number, to ruleset number string, from ruleset number, to ruleset number

Query Number 609 606 607

BLP Commands Queries

STRING IN BLP COMMAND OF BUTTONS STRING IN BLP COMMAND OF MENU STRING IN ENTRY OR EXIT COMMANDS

Parameters string, from form number, to form number string, from form number, to form number string, from form number, to form number

48-15

48

Information Tools Using the Search Tools in Batch

Query Number 2275 2277 2279

DBMS Adapter Information Queries

LIST ALL PHYSICAL MAPPING LIST PHYSICAL RECORDS FOR IO MODULE LIST PHYSICAL SEGMENTS BY TABLE NAME

Parameters

I/O module name table name

48-16

Chapter 49 Cleanup Tools

Cleanup Tools provides a set of queries that are used to obtain information to assist in cleaning up the following incorrect definitions in the database: Unused objects Improper definitions (e.g. operations with no target) Field mismatches
It is recommended to delete such objects.

To access Cleanup Tools:

1 From the Navigation pane of Development Workbench select the Tools tab. 2 Select Cleanup Tools. The Cleanup Tools (100022) menu is displayed:

49-1

49

Cleanup Tools Cleaning up the Database

49.1 Cleaning up the Database

Perform a search for improper fields, composites, classes, operations and rules: 1 Select the Fields with Non-Existing Subject option to search for fields with a non-existing subject. 2 Select the Classes without Composite option to search for classes without composites. 3 Select the Classes without Fields option to search for classes without fields. 4 Select the Composite without Classes option to search for composites without classes.

49-2

Cleanup Tools Cleaning up Constructors

5 Select the Operations with Non-Exist. Target option to search for operations with non-existing target (composite, class or class in composite). 6 Select the Rules with Non-Existing Target option search for rules with nonexisting target. 7 Select the Different in Target Compilation option to search for rules with target in the compilation (class 731) that are different from target in the definition (class 446).

49.2 Cleaning up Constructors

Perform a search for constructors with: Improper or no target values (see "Fixing Constructors with Improper Targets or with No Targets" on page 49-3). Improper Use or parents (see "Fixing Constructors with Improper Use/Parents" on page 49-3). Field mismatches (see "Fixing Field Mismatches" on page 49-4).

Fixing Constructors with Improper Targets or with No Targets

1 Select the Operations with Different Target option to find constructors with constructor class not equal to the target class of the constructor's operation. 2 Select the Operations without Target option to find constructors with an operation that has no target. 3 Note the current status of the constructor to be changed. Change its status to R. 4 Delete the constructors that have improper targets. Since their status is R the underlying basic definitions (composite, class, operation,...) are not deleted. Constructors whose status was changed to R are reversed from Basic later.

Fixing Constructors with Improper Use/Parents

1 Select the Constructor Use and Parent option to find constructors with improper Use or parents. 2 Compare the result with the constructor structure in composite 3.

49-3

49

Cleanup Tools Cleaning up Constructors

3 Note the current status of the constructor to be changed. Change its status to R. 4 Set the Use to OneToOne if the constructor class has this option in composite 3. 5 Change the constructor status back to its previous value. 6 Repeat steps 3-5 for all constructors that require change.

Fixing Field Mismatches

Fix the following field mismatches between: Field definitions and field definitions in constructors Field in class definition and field definitions in constructors Field in operation definition and field definitions in constructors

To fix field mismatches:

1 Select the Fields option. The Constructor for Fields Cleanup form is displayed:

2 Select the Mismatches with Field Def option to obtain a printout of all mismatches with field definitions (does not include mismatches with field options).
49-4

Cleanup Tools Cleaning up Constructors

3 Select the Mismatches with Field Options option to obtain a printout of all mismatches with field options. 4 Select the Mismatches with Field in Class option to obtain a printout of all mismatches between the field in constructor definition and field in class options. These should be fixed manually using operation 178. 5 Select the Mismatches with Field in Oper option to obtain a printout of all mismatches between field in constructor definition and field in operation definition. 6 Select the Fields in Constructors Classes option to obtain a printout of all fields that are in the class of the constructor but are not in the constructor. 7 Select the Fields in Constructors Oper option to obtain a printout of all fields that are in the operation of the constructor but are not in the constructor.

49-5

49

Cleanup Tools Cleaning up Constructors

49-6

Chapter 50 Introduction to Queries

eMerge has a query and data manipulation language. To define a query you must define the following:

The query identifier (the name, and optionally the number, that uniquely identifies the query). The query instruction statements.

For more details on query definition and usage see "Basic Queries" on page 51-1.

50.1 Defining a Query

Query definitions (the query identifier and the query instruction statements) are defined via the Query Definition form. 1 Right-click the Queries option on the Logic tab. A pop-up menu is displayed.

50-1

50

Introduction to Queries Defining a Query

2 Choose the New Query option:

50-2

Introduction to Queries Defining a Query

The Query Definition form is accessed:

3 Enter a number and a name for the query in the Query textboxes. The name can be up to 32 characters, consisting of letters, digits, blanks and any of: - _ ' " . and #. The number must identify the query uniquely. It is recommended that the name uniquely identify the query across all constructors. You can execute a query via its name only, if the name is unique. 4 Enter the text of the query instruction statement in the Query Text textbox. See "The Query Instruction Statement" on page 50-4. Everything else on the form can be left blank. 5 Click OK.

50-3

50

Introduction to Queries Queries in a Multi-Language Environment

If the query definition is not valid, an error message with the reason is displayed. The syntax of the query text is not checked on entering the query, only during compilation of the query (see "Executing a Query from the Query Definition form" on page 50-7).

50.2 Queries in a Multi-Language Environment

If more than two languages are defined at your site when a query is compiled, that query, at run time, inserts the LANGUAGE command into the operation file (TRAN file). This command specifies the current language at the time the query was run.

50.3 The Query Instruction Statement

Selection Statements and Output Statements
A query is made up of two types of instruction statements: Selection statement To extract the desired data from the database. A query must have a selection statement. Output statements To format and output the selected data. The most common output statement is a report statement which sends the output to a listing. (For detailed information on output statements see "Basic Queries" on page 51-1.) Output can also be sent to a form, the database, or to an operation file. A query can have any number of output statements. Example: To produce output that is a report that shows, for each employee, the employee name, salary, and the hire date, the appropriate statements are as follows: The selection statement The report statement The query looks like this:
for all employee. print employee-name salary hire-date. for all employee.

print employee-name salary hire-date.

50-4

Introduction to Queries The Query Instruction Statement

Object Names, Numbers and Synonyms

In queries, objects in the knowledgebase such as fields, classes, composites and operations can be referenced by their name and/or number. If the field name is not unique in the knowledgebase (e.g. the same field name is defined in several classes) it must be clarified with the name of the class where it is defined. The name can be replaced by a synonym. A synonym is given automatically to an object upon object definition unless the NoAutoSynonyms option has been defined for the database. The automatically defined synonym consists of a letter (alpha character) specific to the object type concatenated with the unique object number: F S R T field class composite operation for example: F3000 for example: S33 for example: R33 for example: T3000

You can also define your own synonyms for an object (see "Using Synonyms" on page 5-5). If the automatically defined synonym is kept unique (by not defining your synonyms or naming objects with the automatic synonym naming convention), the automatically defined synonym can be used to uniquely reference an object.

Statement Syntax Rules

The query statements can be written in upper or lower case letters or a combination of both. When you display the query definition, it appears exactly as you entered it, except for the query name, which always appears in upper case letters.

50-5

50

Introduction to Queries Using Queries with a Century Window

The following rules apply when writing a query:

Any space or special character within the name must be replaced by a dash (-). Trailing special characters must be deleted. Multiple dashes must be replaced by a single dash. Each statement must end with a period. (The rules for queries are the same as for rules, except that each rule contains only one statement, and, therefore, there is only one period per rule.) Only one selection statement is allowed per query. You must have at least one output statement.

The CompilationNeeded Option

The CompilationNeeded option is automatically assigned to a query that has been changed since the last time it was compiled. See "Compiling a Query Without Executing It" on page 50-7.

50.4 Using Queries with a Century Window

If a century window is used, as described in Business Integrity Server Administration Guide, any queries that are compiled should have a fourdigit year for any constants that refer to date fields. This is true even if the date field has a two-digit year. A two-digit constant for the year in a query is handled as follows:

If a century window is defined, an error is displayed, telling you to change the constant to a four-digit year. If a century window is not defined, a warning is displayed and the constant is considered to indicate a 19xx-year.

50.5 Compiling and Running a Query

Before the query can be run, it must be compiled. Any syntax errors in the text of the query are reported when the query is compiled. You can compile and run the query in one step. If you made any errors (syntax or logic errors), an error message is displayed either during compilation (syntax errors) or execution (logic errors) of the query. See Chapter 58, Common Query Errors for examples of common errors and how to correct them.
50-6

Introduction to Queries Compiling and Running a Query

Compiling a Query Without Executing It

If you do not want to see the output of your query immediately, but still want to check it for syntax errors, you can compile the query. Display the Query Definition form and click the Compile button.

Executing a Query from the Query Definition form

Display the Query Definition form and click the Execute button.

Executing a Query via the QUERY Command

Enter the QUERY command, followed by the query name or number, into the Execute Command box. The QUERY command syntax is:

Example:

If the name of the query is Employee Pay:

Press <Enter> to execute the command. If the query needs to be compiled, it is compiled first.

Executing a Query via the RUN Command

Using a RUN command, instead of the QUERY command, executes a compiled query. If the query is not compiled, an error is issued.

50-7

50

Introduction to Queries Viewing the Query Output

50.6 Viewing the Query Output

When you run a query the output is displayed as defined in the query definition (form or report). For a report listing, the sample query is shown in the Listing as follows.

If the output is directed to a data entry form, the form is displayed. See "Sending Query Output to a Data Entry Form" on page 53-1.

50.7 Viewing Sample Output via the DEMOQUERY Command

Before executing a query, or before you have real data in the database, you can see an example of what the output for the query will look like. By running the DEMOQUERY command you can see a sample page of the specified output report filled in with eMerge-supplied dummy data. In order for the DEMOQUERY command to work, the query must contain a PRINT statement. There are two ways of issuing the DEMOQUERY command:

from the Query Definition form from the Execute Command box

From the Query Definition

Display the Query Definition form for the particular query and click the DemoQuery button to issue the command.

50-8

Introduction to Queries Viewing Sample Output via the DEMOQUERY Command

From the Execute Command box

Enter DEMOQUERY QUERY_NAME into the Execute Command box. Instead of the name you can enter the query number. Press <Enter> to execute the command. Example: If the name of the query is Salary:

Example
Assume the following query definition:
for all employee where salary < 19000. print employee-name salary hire-date. break space by employee-name salary. break frame by division. total frame salary. average report salary. title Low Salaried Employees. top CONFIDENTIAL. bottom Prepared By Personnel Dept..

Clicking the DemoQuery button produces the following listing output:

50-9

50

Introduction to Queries Viewing Sample Output via the DEMOQUERY Command

In the sample output, characters replace the values that would appear in the output when you execute the query. Each field is filled with the specific characters to its maximum length. Character C Z D M Y F Meaning Character field Numeric field The day in a date The month in a date The year in a date Hexadecimal field

50-10

Chapter 51 Basic Queries

The syntax of all eMerge queries consists of statements having keywords and parameters. The keywords define the purpose of the statement. The parameters are user supplied and further define the query. An eMerge query consists of a selection statement and one or more output statements. Selection Statement Output Statement A selection statement selects and qualifies the data for the query. It must include a FOR keyword (and optionally a WHERE keyword). See "Selecting and Qualifying Data for a Query" on page 51-1. An output statement defines the types and formats of the query output. The following are the kinds of output statements:

report statement See "Arranging the Data Printed in a Report" on page 51-4. define statement - virtual fields and views See "Using Virtual Fields" on page 52-6. query output form statement See Chapter 53, Sending Query Output to a Data Entry Form. update statement See Chapter 55, Updating the Database Using Queries. extract statement See Chapter 54, Extracting Raw Data to an External File.

51.1 Selecting and Qualifying Data for a Query

A selection statement uses the FOR and optionally the WHERE statements.

51-1

51

Basic Queries Selecting and Qualifying Data for a Query

The FOR Statement

The FOR statement identifies the context of the query:

The query context is the data stored in the class, identified by its name. Sometimes, the class is qualified by the name of the independent class in the composite hierarchy. Example: If the database contains more than one class called Employee, you must specify the composite hierarchy to which the class belongs. The following query specifies the Personnel composite hierarchy:
for all employee of composite personnel. print employee-name salary hire-date.

The WHERE Statement

Use the WHERE statement to qualify the data included in the query context selected by the FOR statement:

Example: To see data on employees whose salaries are less than $19,000, use a query like:

51-2

Basic Queries Selecting and Qualifying Data for a Query

for all employee where salary < 19000. print employee-name salary hire-date.

The WHERE statement comes immediately after the FOR statement.

You can write the WHERE statement as part of the FOR statement, without a period after the FOR statement, as in the example query above.

The query produces the following report:

The WHERE statement can be used to set criteria in various different ways. You can specify as many criteria as you want on the data selected, using the keywords AND and OR as logical connectives. Following are some examples of using the WHERE statement: where statement
where employee-name 'HENLEY TIM'. where sex is 'F'.

Meaning Requests information only about the particular employee whose name is Henley Tim. Requests information about female employees only. The IS keyword is optional. employees whose salaries are higher than $19,000. Requests information about those employees who are female OR whose salaries are greater than $19,000, but not necessarily both. Requests information about those employees whose salaries are in the range between $10,000 and $19,000.

where sex is 'F' and salary > 19000. Requests information about those female

where sex is 'F' or salary > 19000.

where salary is 10000 to 19000.

51-3

51

Basic Queries Defining Output Type and Style for a Query

where statement
where salary gt min-salary.

Meaning Requests information abut those employees whose salaries are greater than the minimum salary. Two fields are compared here: SALARY and MIN-SALARY. The object of the comparison operator does not have to be a constant; it can also be the value of a field. Requests information according to a variety of criteria, combining a field, a range, and a constant value.

where salary is min-salary, 2000 to 3000, gt 5000.

A non-numerical constant in a WHERE statement must be enclosed in single quotes; otherwise, it will be taken as a field name. An example of where single quotes are necessary is in the selection of all female employees. The F in the WHERE statement is enclosed in single quotes as follows: where sex 'F'.

51.2 Defining Output Type and Style for a Query

The output statement defines the type of output for the query (see"Basic Queries" on page 51-1 for the types of output statements). A commonly used output statement type is a query listing in the form of a report. The REPORT statement is used to clarify and style the listing into the desired report format. The REPORT statement uses the following keyword statements:

statement statement TEXT statement HEAD statement SORT statement

PRINT BREAK

51.3 Arranging the Data Printed in a Report

The PRINT statement is used to format an output report.

51-4

Basic Queries Arranging the Data Printed in a Report

Printing Field Values

Specify which fields to print out in the report using the PRINT statement:

The PRINT statement causes the query to display the values of all the fields listed in the statement, for each class occurrence selected in the FOR statement. Looking at the first example query again:
for all employee of composite personnel. print employee-name salary hire-date.

The values for the fields produced by this query are printed in each line in the order specified in the PRINT statement:

The order in which the employees appear on the form is the order of the key field (not shown in this report). If the class was defined without a key, the order is the order in which the data was entered into the database.

51-5

51

Basic Queries Arranging the Data Printed in a Report

Ordering the Field Values

Use the BY keyword in the PRINT statement to control the order of the output lines. Example: follows: Writing the BY keyword directly before employee-name as

for all employee. print by employee-name salary hire-date.

The keyword BY causes the query to sort the output lines in the report alphabetically, according to the employee names. The query produces the following report:

This query and the query on page 51-5 are identical except for the use, in this case, of the BY keyword. In this query output, the employees appear sorted alphabetically. The BY keyword does not change the order in which the field values appear in each line (i.e. Employee Name, Salary and then Hire Date). The BY keyword need not immediately follow the keyword PRINT in the PRINT statement. The field by which the data is sorted can appear anywhere in the PRINT statement as long as BY appears directly in front of it.

51-6

The BY keyword applies only to the field immediately following it in the PRINT statement.

Basic Queries Arranging the Data Printed in a Report

Example: The following query prints the same information, sorted by salary instead of by Employee Name:
for all employee. print employee-name by salary hire-date.

The query produces the following report:

The data items are sorted in increasing order by default. If you want them sorted in decreasing order, specify the word DESCENDING after the word BY as follows:

for all employee. print employee-name by descending salary hire-date.

Defining Multiple Sorts

You can use the BY keyword more than once in a PRINT statement to sort data within already sorted data. Example: To sort the employees by salary, and then within each salary grouping, to sort by the date the employee was hired, use the BY keyword twice:
for all employee. print employee-name by salary by hire-date.

51-7

51

Basic Queries Arranging the Data Printed in a Report

The query produces the following report:

The positions, in the report, of Chapman Chris and Baria George have changed.

The BY keywords are acted upon in the order in which they appear in the PRINT statement.

Removing the Separators Between Field Values

Use the WITH keyword in the PRINT statement to remove the separator between field values. Example: To print two fields together on a line without separators between them:
for all employee. print by employee-name salary with hire-date.

The query produces the following report:

51-8

Basic Queries Arranging the Data Printed in a Report

Compare this method of combining fields with the method described in "Specifying the Field Delimiter" on page 51-19. You can use the WITH keyword more than once in a PRINT statement.

Printing More than One Field in a Column

Use the OVER keyword in the PRINT statement to allow more than one field to be printed in a single column. This is particularly useful when the physical width of the form or printer is not big enough to include all the fields without scrolling. Example:
for all employee. print by employee-name salary over hire-date.

The query produces the following report:

You can use the OVER keyword more than once in a PRINT statement as in the following query:
for all employee. print by employee-name over id-no position over salary grade over hire-date.

The statement can continue over more than one line.

This query causes each of the three field pairsEmployee Name/ID No, Position/Salary, and Grade/Hire Dateto be printed in the same column. The first field in the pair is printed above the second one. The query produces the following report:

51-9

51

Basic Queries Breaking Up the Output

Up to six fields can be printed in a single column, i.e. using the OVER keyword five times in a continuous chain. For example:

for all employee. print by employee-name over id-no position over salary over grade over hire-date.

51.4 Breaking Up the Output

Instead of having line after line of data in your report, you can create physical divisions between groups of data. Do this using the BREAK statement:

The lines can be broken up either by putting a SPACE between them, drawing a FRAME around them, starting on a new PAGE, or starting a new SECTION. Each kind of break is called a break level. You can nest break levels in a query. The lowest (smallest) break level is a space break, followed by a frame break, a page break, and then a section break. There are different BREAK statements for each of these different break levels. When a BREAK statement is used, a field is specified to trigger the break. This means that each time the data in that field changes, a break occurs. You can specify more than one field to trigger the break.

51-10

A field that triggers a break is referred to as a break field.

Basic Queries Breaking Up the Output

Breaking with Spaces

Use the BREAK SPACE statement to produce a visual separation between designated fields. Each time the information in the specified field changes, a blank line is produced. In addition, when the data in the break field does not change, it is not repeated. Example: To see which employees work on which projects, when employees work on more than one project at a time:
for all employee. print by employee-name project-name position salary.

The query produces the following report:

There are two lines of output for Baria George and Bunche George and three for Carr Gerald. For each of these three employees, the lines are exactly the same except for the project name. The report looks crowded because redundant information is printed several times. Use the BREAK SPACE statement to clean up the display of the data:
for all employee. print employee-name project-name position salary. break space by employee-name position salary.

The fields are sorted according to the break fields in the BREAK SPACE statement and not, as previously, by the fields in the PRINT statement.

51-11

51

Basic Queries Breaking Up the Output

The query produces the following report:

The information contained is identical in both reports, except that blank lines have been inserted and duplicate field values have been eliminated in the second one. Compare this method of combining fields with the method described in "Changing the Space Between Lines of Data" on page 51-18.

Breaking with Frames

Use the BREAK FRAME statement to cause a box (frame) to be drawn around each logical grouping of information. Each time the value of the break field in the BREAK FRAME statement changes, a new frame is drawn. In addition, a heading with the name of the break field and its value appears on top of each frame. The frames are sorted according to the break field. Within each frame the sorting follows the normal sorting defined by the BY keyword (either in the PRINT statement or a BREAK SPACE statement). Example: To see which employees work in what division and on which projects each employee is working, break the report by divisions:
for all employee. print employee-name project-name position salary. break space by employee-name position salary. break frame by division-name.

51-12

Basic Queries Breaking Up the Output

The query produces the following report:

Since Division Name is the break field in the BREAK FRAME statement, each time the Division Name changes, a new frame is drawn, and the division name itself appears above the frame as part of the title.

The first employee does not belong to any division. That is why the corresponding Division Name is left blank in the report.

Breaking by Page
Use the BREAK PAGE statement to force each logical grouping of information on to a new page. A heading, with the name of the break field, appears at the top of each new page. The titles of the data fields appear immediately below the heading. Example: Consider the following query which differs from the previous example only in the break level used.
for all employee. print employee-name project-name position salary. break space by employee-name position salary. break page by division-name.

The query produces the following report:

51-13

51

Basic Queries Breaking Up the Output

Each Division Name value appears on a separate page. When printed, the report is on a number of separate pages.

Break by Section
Use the BREAK SECTION statement to force each logical grouping of information into a separate report section. A change in the value of any of the fields specified, produces a separate report with a new separator page. A heading, with the name of the break field, appears on a new page. The titles of the data fields appear immediately on the next page. Only one section break level can be defined for each report. Example: Consider the following query which differs from the previous example only in the break level used.
for all employee. print employee-name project-name position salary. break space by employee-name position salary. break section by division-name.

51-14

Basic Queries Breaking Up the Output

Each Division Name value appears as a header on a separate page starting a new report. The titles of the field data and the field data values appear on the page following the header page.

Combining Different Break Levels

You can use more than one kind of break statement in a single query. Example: In the output of the query illustrating the BREAK PAGE statement above, possible repeated data is eliminated using the BREAK SPACE statement. In addition, a blank line is printed each time the employee name changes within a frame.

Any combination of break levels can be used, but there can be only one BREAK statement for each level in a query.

Including a Break Field in the PRINT Statement

When the first break field in a BREAK FRAME statement also appears in the PRINT statement, the result is slightly different. In the following query, division-name appears both in the PRINT statement and as the break field in the BREAK FRAME statement:
for all employee. print employee-name division-name salary hiring-date. break space by employee-name division-name salary. break page by division-name.

51-15

51

Basic Queries Improving a Report's Appearance

The query produces the following report:

Each time the division name changes, a new frame is drawn but without a blank line and a heading above it. In addition, the division name itself appears in the first line within each frame, rather than as a title above the frame.

51.5 Improving a Report's Appearance

Use the REPORT TEXT statement to define text to appear at the beginning and end of the report:

The text must be surrounded by single quotes ('). It can contain any character and be up to 78 characters in length (including the quotes). Multiple REPORT TEXT statements can be specified for a given query. You can repeat a REPORT TEXT statement with different text, if 78 characters is not enough, or you want the text on more than one line. The text appears centered by default. Change the position of the text by using either the LEFT or RIGHT keywords in the REPORT TEXT statement.

51-16

Basic Queries Improving a Report's Appearance

Adding a Title to a Report

Use the TITLE keyword to define a title to appear at the top of the first page of the report. Example: To have the report text Low Salaried Employees appear as the title of the report on the first page of the report:
for all employee. print employee-name project-name position salary. break space by employee-name position salary. break frame by division-name. title Low Salaried Employees.

The report produced by the query has the title on the first page as follows:

Adding Header and Footer Text

Use the TOP keyword to produce a header to appear on the top of each page. On the first page, the header appears directly below the title. Use the BOTTOM keyword to produce a footer to appear on the bottom of each page. Example: To insure that the heading CONFIDENTIAL appears at the top of each page, and Prepared by Personnel Dept. appears at the bottom of each page, add the following REPORT TEXT statements to the previous query:
top CONFIDENTIAL. bottom Prepared by Personnel Dept..

51-17

51

Basic Queries Improving a Report's Appearance

The query produces the following report:

Customizing the Layout

Use the OPTIONS statement to customize the layout of your report. A few of the many possibilities are demonstrated in the examples below. For a detailed discussion of all the different options available, see the description of the syntax of the OPTIONS statement in the General Reference. Changing the Space Between Lines of Data By default, the query output is single spaced. Use the OPTIONS SPACE statement to change the spacing:

for all employee. print by employee-name salary hiring-date. options space double.

The query produces the following report:

51-18

Basic Queries Improving a Report's Appearance

If the OPTIONS statement in the query had been OPTIONS SPACE TRIPLE, there would have been two blank lines between each line of data in the report rather than one. Numbering the Lines of Data Unless otherwise specified, all lines are consecutively numbered from the beginning of the report until the end.

Use the OPTIONS NUM NO statement to eliminate numbering entirely. Use the OPTIONS NUM FRAME statement to start numbering from one (1) at the beginning of each new frame. Use the OPTIONS NUM PAGE statement to start the numbering from one (1) at the beginning of each new page. If the OPTIONS statement in the above query were OPTIONS

Example:
NUM NO:

options num no

The query produces the following report:

Specifying the Field Delimiter

Use the OPTIONS SEP statement to change the delimiter between the field values in each report line (the default is a vertical bar preceded and followed by a space: | ). Specify the new delimiter between single quotes. Example: used:
OPTIONS SEP

If the OPTIONS statement in the above query were an statement, the delimiters are removed and a space is

options sep .

The query produces the following report:

51-19

51

Basic Queries Defining Comment Text for a Query

Not only are the separators between fields blanks instead of vertical bars, but the outside lines that form the sides of the box around the report data are also removed. Compare this with the results of using the WITH keyword in a PRINT statement in "Removing the Separators Between Field Values" on page 51-8.

Combining Different Options

You can specify multiple options in the same query either by defining multiple OPTION statements or by defining multiple options in the same OPTION statement. Example: To define double spacing, suppress numbering, and use spaces as the field delimiter, all in the same report, write the following query:
for all employee. print by employee-name salary hiring-date. options space double num no sep .

The query produces the following report:

51.6 Defining Comment Text for a Query

You can add comment lines to the text of the query. You can also define more general help text for a query. Insert a comment in a query by starting the comment line with /*.

51-20

Basic Queries Renaming a Field for a Query

/* using a blank to separate field values options sep .

51.7 Renaming a Field for a Query

If the field name is not suitable for the report (e.g. it is too short or too long) you can rename the field for the purposes of the output. The field is renamed in the same way that you rename a field for any listing. See "Changing a Field Name Displayed in a Listing" on page 47-3.

If you define a title for a field, it is used in the output of every query that lists the field in its output. See "Renaming a Field Using a Virtual Field" on page 52-10 for details on how to change the title for a specific query.

You can also change the name that you use in the text of a query (e.g. if the field has a long name and is used often). 1 From Modeler, right-click the Concept and select Object>Concept Design from the pop-up menu that is displayed. The Concept Design form is displayed. Select the field whose name you want to change and right-

51-21

51

Basic Queries Renaming a Field for a Query

click in the field. Select Detail from the pop-up menu that is displayed. The Field Definition form is displayed:

2 Select the Synonym tab.

51-22

Basic Queries Using Possible Values in the Query Output

3 Enter the name you want in place of the field in the Synonyms textbox. The synonym can be used for the field in queries and rules.

51.8 Using Possible Values in the Query Output

If a field has possible values defined for it, where each possible value has a meaning, the meaning can be used in your query. Example: Instead of showing the code for marital status you can define possible values where each value is defined with a meaning (e.g. MMarried, S-Single, D-Divorced) and use the meaning in the query output.

51.9 Using Statistical Functions

Use the STATISTICAL FUNCTION statement to produce statistics for the break level specified in the statement (section, page, etc.):

If a function is requested for a particular break level, it is applied at every higher break level requested in the query, and also for the entire report (unless indicated otherwise). When a break level is not specified in a STATISTICAL FUNCTION statement, the function is performed over the entire report. Thus, report is considered to be the default break level for statistical function statements. It is higher than all the other break levels. You can include a field in a STATISTICAL FUNCTION statement even though it is not included in the PRINT statement.

Producing Statistics Over the Entire Report

The simplest use of the STATISTICAL FUNCTION statement is for the whole report. Example: To report the total salaries for those employees whose salaries are less than $19,000:
51-23

51

Basic Queries Using Statistical Functions

for all employee where salary < 19000. print by employee-name salary hire-date. total salary.

If the break level is not specified, the salaries are totaled over the entire report.

The query produces the following report:

You can explicitly specify the REPORT keyword in a function statement (e.g. total report salary. instead of total salary.).

Producing Statistics by Frame

Example: To know the total of all the salaries less than $19,000, not just for the entire company but also for each division in the company:
for all employee where salary < 19000. print by employee-name salary hire-date. break frame by division-name. total frame salary.

The employees are grouped by division, via the BREAK FRAME statement. The TOTAL statement computes the salary totals for each frame. The query produces the following report:

51-24

Basic Queries Using Statistical Functions

Since the total was requested by frame, a total appears at the end of each frame of all the salaries in that frame. A total is also displayed for the entire report.

The query calculates the statistical function for the whole report and for all break levels explicitly mentioned in BREAK statements that are higher than the one specified in the function statement.

If the above query had also contained a BREAK SPACE statement and a BREAK PAGE statement, then totals for the salaries would have been printed at the end of each page break, but not at the end of each space break. This is because SPACE is a lower break level than FRAME (and the totals were requested by FRAME). In order to print totals (or any other statistical function) for a specific break level only, and to suppress automatic printing for higher break levels, use the ONLY keyword. That is, to obtain a total for the frame break only, without the automatic totaling over the entire report, write a query as follows:
for all employee where salary < 19000. print by employee-name salary hire-date. break frame by division-name. total frame only salary.

The query produces the same output as the previous query but without the last line of TOTAL FOR QUERY.

Performing Statistical Functions by Break Field

Instead of requesting a statistical function by break level, you can request it by the break field (i.e. the name of the field that causes the break). Example: To total salaries by frame only:

for all employee where salary < 19000. print by employee-name salary hire-date. break frame by division-name. total for division-name only salary.

This produces the same output as the above query. The name of the break field (in this case, Division Name) preceded by the FOR keyword is substituted for the break level itself (in this case, frame). The field name upon which the statistical function is performed (in this case, Salary)
51-25

51

Basic Queries Using Statistical Functions

follows immediately after. The ONLY keyword appears here also, to specify that you want totals only every time the value of Division Name changes (i.e. every time there is a frame break), and not at the end of the entire report.

Combining Statistical Functions

You can use any number of statistical functions within a single query. You can also include any number of fields in a single STATISTICAL FUNCTION statement. Example: To calculate the total of the salaries in each division, the average of the salaries in each division, the minimum salary in each division, the earliest starting date of the employees in each division, and the totals and averages for the entire report, but not the minimum salary or earliest starting date over all the employees:
for all employee. print by employee-name salary hire-date. break frame by division-name. total frame salary. average frame salary. minimum frame only salary hire-date.

The query produces the following report:

The ONLY keyword in the MINIMUM statement relates to the break level specified and applies to all the fields in the statement. Thus, minimums are not printed at the end of the entire report for either Salary or Hire Date. If you want a minimum printed at the end of the whole report for Salary but not for Hire Date, replace line 30 in the query with the following two lines:

51-26

Basic Queries Using Statistical Functions

minimum frame only salary. minimum frame hire-date.

Using Statistical Functions in the PRINT Statement

You can write statistical queries by using statistical functions within the PRINT statement. This type of PRINT statement allows you to print only statistical values. In order to do this, specify the BY keyword followed by the name of the field that you want printed with the results of the function statement. Include the keyword defining the statistical function in the PRINT statement, followed immediately by the field on which it is to be performed. You can include more than one statistical function in a single PRINT statement. In addition, you can specify one function keyword multiple times in a single PRINT statement. Details of all values that are used to calculate the statistical function are not printed in the report. Example: To see the total salary for all the employees in each division, and the average salary for all the employees in each division without seeing any details about the specific employees:
for all employee. print by division-name total salary average salary.

The query produces the following report:

In the above example, you wanted totals and averages to be computed over all the employees in each division. Thus, Division Name is the field specified in the PRINT statement. This causes a line to be printed for each value of the field Division Name with the total salaries and the average salaries for all the employees in that division, displayed on that line. The

51-27

51

Basic Queries A Summary of Basic Query Statements

detailed values of the salary for each employee are not shown in the report.

Remember to include the BY keyword before the break field.

51.10 A Summary of Basic Query Statements

The different query statements may appear in a query in any order, except for the following:

The FOR statement must be the first statement in the query. The WHERE statement (if used) must follow immediately after the FOR statement.

The following table shows which statements are mandatory and which are optional and gives a brief description of each Statement
for where

When to use it Mandatory - Must be the first statement. Selects the data to be included in the query. Optional - If used, must be the second statement or the second part of the FOR statement. Specifies criteria to narrow the range of the data selected by the FOR statement. Mandatory - when printing a report. Optional - when using EDIT, EXTRACT or UPDATE statements. Indicates which fields are included in the report and the order in which they appear on the line. PRINT can be used in conjunction with a number of different keywords (see the keyword table below for explanation). Optional - Breaks the data into logical units by inserting a SPACE between them, drawing a FRAME around them, starting a new PAGE, or starting a new SECTION. Optional - Used to enhance the appearance of the report by allowing the definition of a title, header, or footer for it. Any combination of these statements can be used and more than one statement of each type is allowed.

print

break

report text: title top bottom

51-28

Basic Queries A Summary of Basic Query Statements

Statement
options

When to use it Optional - Used for issuing additional instructions to customize the report, e.g. controlling the spacing, numbering, delimiters between field values, etc. Several options can be defined in one OPTIONS statement or several separate OPTIONS statements. Optional - Used to perform statistical calculations on the data and print the results in the report. Any combination of these statements can be used and more than one of each type of statement can be used in a single query.

statistical function: average count maximum minimum total

The following table gives a brief description of the keywords that can be used in the PRINT statement: Keyword
BY

Description Directs the output lines in the report to be sorted according to the value of the field that directly follows the BY keyword. More than one BY can appear in a PRINT statement. Specifies that the field immediately preceding and the field immediately following the WITH keyword be printed together on a line without any delimiter between them. Specifies that the field immediately following the OVER keyword be printed directly below the field immediately preceding the OVER keyword. Allows up to six fields to printed in a single column in the report.

WITH

OVER

51-29

51

Basic Queries A Summary of Basic Query Statements

51-30

Chapter 52 Extending the Use of Queries

You can enhance your queries by using parametric queries, nested queries, object ranges, virtual fields and views. You can also query knowledgebase structures.

52.1 Parametric Queries

A field may be defined as a parameter to a query. This allows you to produce different reports depending on the value input to the parametric field, without having to change the query itself. You can define any number of fields in a query as parameters. A query containing a parametric field is called a parametric query. Instead of a numerical constant to qualify the data, use the field name, with a @ in front of it, in the text of the query. Example: To find out information about all employees whose salaries are less than a certain amount which will vary, depending on who wants to see the report:
for all employee where salary < @salary. print employee-name salary hire-date.

On executing the query, the following prompt form is displayed to allow the user to enter a value for the parameter:

The resulting report depends on the value entered to this form.

Parametric Queries in Batch

You can run parametric queries in batch.

52-1

52

Extending the Use of Queries Including a Query in Another Query

Parametric Queries via a Command

You can run a parametric query directly by issuing the QUERY command in the Execute Command box of Development Workbench, and including the parameters as part of the command:
query employee-salaries,19000

Any spaces in the query name must be replaced by hyphens if a parameter value is included in the command. If there is more than one parameter in the query, the structure of the command is as follows:

where <queryname> is the name (or number) of the parametric query. The values of the parametric fields then appear in the statement separated by commas, in the order in which the parametric fields appear in the query.

Calculating Parameter Values

Use rules, attached to the query, to calculate the values of parameters used in the query.

52.2 Including a Query in Another Query

You can embed one query within another query. When you run the query, all of the included statements are inserted into the query and are compiled and executed as part of the query. Include a query that contains statements, or groups of statements, that are commonly used in many queries. A query can contain any number of INCLUDE clauses. You can also nest an INCLUDE clause in another INCLUDE clause, up to a maximum nesting level of three.

Defining and Including a Query

1 Define the query to be included. The included query need not be a full, executable query. It can be part of a query or even part of a statement.
52-2

Extending the Use of Queries Improving Performance When Using Object Ranges in Queries

2 Include the query in the appropriate place by typing the name (or number) of the query to be included after the keyword %INC. The percent sign (%) is part of the syntax.

Example
To include the standard top and bottom text used on all reports issued by the personnel department, define a new query to include the standard top and bottom text used by the personnel department:
top CONFIDENTIAL. bottom Prepared by Personnel Dept..

Include the query in every report issued by the personnel department:

for all employee. print employee-name salary hire-date. %inc personnel-dept-text

The include clause does not end with a period since the statements in the included query end with a period.

52.3 Improving Performance When Using Object Ranges in Queries

You can use the following method to improve performance when referencing ranges for an object (i.e. for a field, class, composite, operation, form, or ruleset) in a query: 1 Define a ruleset, triggered by your query, that prepares parameters for program SAPFRANG (21) and runs the program. The SAPFRANG (21) program filters the object ranges supplied by the user (in his query) and returns a set of filtered subranges that are used instead of the user supplied range. 2 Include one of the system queries, listed in "System Queries" on page 52-4, in your user-defined query to prepare a set of subranges to contain only the user objects. Each of the system queries can be included in any user query, via the INCLUDE clause. The following is an example of the INCLUDE clause:
%Include field-from-to

For more on INCLUDE clause syntax, see General Reference

52-3

52

Extending the Use of Queries Improving Performance When Using Object Ranges in Queries

The method generates subranges that are only applicable to the user (i.e. system ranges are excluded). The generation is transparent to the user and results in a more efficient search over the range given by the user. Example: A user query performs a search on forms between form numbers 30000 and 52000. A system query (form-from-to) is included in the user query. The user query triggers a ruleset that calls program SAPFRANG (21). The actual search is then performed on the set of calculated subranges (51000-52000)those that contain only user forms.

System Queries
System queries are available for the following objects: Object field class composite operation form ruleset System Query Name field-from-to class-from-to composite-from-to operation-from-to form-from-to ruleset-from-to System Query Number 141 142 143 144 145 146

Using System Queries to Calculate User-specific Object Ranges

Follow these steps to calculate user-specific object ranges. 1 Access the Query Definition (100230) form. 2 In your query text include the system query that deals with the type of object range referenced in your query. Example: If a range of fields is referenced in your query, include the system queryField-From-To, in your query:
%Include Field-From-To

3 From the Logic tab, right-click Rulesets. Choose New Ruleset . The Ruleset Definition form is displayed. 4 Define a ruleset like the system ruleset that is triggered in "Example Using an Object Range in a Query" on page 52-5 (String In Field Names (170) query). The ruleset should calculate parameters for the object (i.e. field, class composite, operation, form, or ruleset) referenced in your query.
52-4

Extending the Use of Queries Improving Performance When Using Object Ranges in Queries

Example: If a range of fields is referenced in your query, define a ruleset like system Ruleset 10100. 5 Return to the Query Definition form and select the Rulesets tab. 6 Choose the ruleset you defined as the ruleset triggered by your query (from the Ruleset Name drop-down listbox). 7 Click OK .

Example Using an Object Range in a Query

Query 170 requires a range of fields and therefore, the field-from-to system query is included:

The field from-to (10100) ruleset is defined in the Query Rulesets tab:

52-5

52

Extending the Use of Queries Querying Knowledgebase Objects

52.4 Querying Knowledgebase Objects

Use a query to get information about the fields, classes, composites, forms etc. that make up your application.

Composite 1 contains classes describing details about fields. Composite 2 contains classes describing the class. Composite 3 contains classes describing the composite. Composite 6 contains classes describing forms.

Example: Field numbers 3300 through 4000 are reserved for the personnel application. To see a list of all the fields in the application, and in addition, to know to which classes each field belongs and what is its input length, define the following query:
for all field where field-no is 3300 to 4000. print field-no field-name class-no of composite class-name of class in composite class. break space by field-name and field-no.

Notice that the field Class No is qualified by the name of the class (class) and that the field Class Name is qualified by the name of the class and the composite.

52.5 Using Virtual Fields

You can define virtual fields in a query. A virtual field exists only during the execution of the query. Use virtual fields to display calculated values, or to change the displayed properties of a field (e.g. a truncated output length). A virtual field defined in a query is not added to the database and does not affect it in any way. You must define a value for a virtual field using an assignment expression. You define a value either in a report statement (e.g. PRINT, BREAK, TOTAL, etc.) or in the DEFINE statement itself. The assignment expression includes the word AS (or one of the synonyms of AS, e.g. the equal sign (=) and EQ) followed by an arithmetic expression that may contain an existing field or fields. Only one assignment is allowed for any given virtual field in a query.

52-6

You can place the DEFINE statement either before or after the report statement in which a value is assigned to it.

Extending the Use of Queries Using Virtual Fields

Example: To see the results of computing a 15% salary increase for employees earning less than $19,000 annually:
for all employee where salary < 19000. define new-sal like salary. print by employee-name salary new-sal as salary * 1.15.

A virtual field called New Sal was defined which has the same characteristics as the field Salary. The PRINT statement is used to assign a value to the new field New Sal which is 15% more than the value of the original field Salary.

Periods are used to separate the integer and fraction parts of the salary calculation. Normally, you must not use periods in the middle of a query statement. For instance, periods in a field name are dropped.

The query produces the following report:

Changing Virtual Field Names

Use the DEFINE statement to change the title of the virtual field displayed in the report by including a TITLE clause in the DEFINE statement. Example: To change the title of the New Sal virtual field to New Salary:

for all employee where salary < 19000. define new-sal like salary title NEW SALARY. print by employee-name salary new-sal as salary * 1.15.

The title must be enclosed in single quotes (').

52-7

52

Extending the Use of Queries Using Virtual Fields

The query produces the following report header:

Changing the Displayed Properties of a Field

Use the DEFINE statement to truncate field values displayed in the report. Example of Truncating a Field You can truncate a field name, for example, the Employee Name field.

for all employee where salary < 19000. print by emp-name as employee-name salary hire-date. define emp-name char 14 title EMPLOYEE NAME.

A virtual character field has a maximum length of 18 characters.

The virtual field Emp Name is created with a length of 14 to shorten the length of values of the Employee Name field from its database length of 20 characters. The virtual field is given the same title as the original field by the TITLE clause. The same values that exist for the original field are assigned to the virtual field by the assignment expression AS Employee Name in the PRINT statement. The query produces the following report:

Note that any employee name longer than 14 characters is truncated (e.g. line numbers 3 and 6).

52-8

Extending the Use of Queries Using Virtual Fields

Example of Reformatting a Date Format

You can display the month and year that the employees were hired (not the exact date):

for all employee where salary < 19000. print by employee-name salary hire-month=hire-date. define hire-month date 5.

The length of the new field is 5 which results in a format of MM/YY instead of DD/MM/YY.

The equal sign (=) is used instead of AS to define the value to Hire Month. AS and = are synonyms in the assignment expression.

The query produces the following report:

Defining the Characteristics for a Virtual Field

You use the DEFINE statement to define the characteristics of a virtual field. Do this either by specifying that the field is a numeric field, a character field or a date field, or that the new field is LIKE a field from the knowledgebase. If you specify that the field is like a field from the knowledgebase, it inherits the characteristics of that field. Following are some examples of DEFINE statements to illustrate this point: Example 1 The name (and title) of the new field is Inc Salary. Its characteristics are the same as those of the existing field Salary.
define inc-salary like salary.

Example 2

The name (and title) of the new field is Temp Salary. The field is numeric with 8 digits.
define temp-salary numeric 8.
52-9

52

Extending the Use of Queries Using Virtual Fields

Example 3

The name of the new field is Temp Salary. It is numeric with 9 digits for the integer part, a decimal point, and two digits after the decimal point. A separate title temporay salary for the virtual field is also defined.
define temp-salary numeric 12.2 title 'temporary salary'.

Periods are used to separate the integer and fraction parts of the numeric definition. Normally, you must not use periods in the middle of a query statement. For instance, periods in a field name are dropped. Example 4 The name of the new field is Short Name. It can include up to 10 characters.
define short-name char 10.

Example 5

The name of the new field is Year Month. It is a date field of the form MM/YY.
define year-month date 5.

Renaming a Field Using a Virtual Field

If the field name is not suitable for the report (e.g. it is too short or too long) you can rename the field for the purposes of the output. You can globally rename the field in the same way that you rename a field for any listing (see "Changing a Field Name Displayed in a Listing" on page 47-3). You can also use the DEFINE statement to rename the field locally, in a specific query. Example: To change the title displayed for the Position field to Job Position use the following DEFINE statement:
define position title job position.

This DEFINE statement does not define a virtual field.

Conditionally Defining Values to a Virtual Field

You can define a virtual field and define a value to this field, dependent on specific conditions. Use the CASE clause within a DEFINE statement. Example: To see the results of computing a salary increase for employees earning less than $19,000 annually, where the percentage increase is dependent on the current salary:

52-10

Extending the Use of Queries Using Virtual Classes (Views)

for all employee where salary < 19000. print by employee-name salary new-sal. define new-sal like salary title NEW SALARY case when salary 0 to 9999 then new-sal=salary*1.2 when salary 10000 to 14999 then new-sal=salary*1.15 when salary 15000 to 17499 then new-sal=salary*1.10 else new-sal eq salary*1.05.

A CASE clause must include an ELSE clause that covers all other cases.

Employees currently earning less than $10,000 would receive a 20% raise, employees earning less than $15,000 would receive a 15% raise, employees earning less than $17,500 would receive a 10% raise and all other employees (earning under the 19000 specified in the WHERE statement) would receive a 5% raise. The query produces the following report:

52.6 Using Virtual Classes (Views)

You can use the DEFINE statement to define views in a query. A view is an alternate way of describing data that exists in a class (either a subset of the data or the data with extra fields that are not included in the class, or the data in the class represented in a different way). The view exists only during the execution of the query. A view defined in a query is not added to the database and does not affect it in any way. Example: To print out, for each employee, the employee's name and the name of that employee's manager:
for all employee. print by employee-name manager-name as employee-name of manager. define view manager from employee using manager-id. define manager-name like employee-name.
52-11

52

Extending the Use of Queries Using Virtual Classes (Views)

The DEFINE statement defines a view named Manager as a special case of the existing Employee class. The Manager ID is used as the key for this view. from employee in the first DEFINE statement (line 15 in the query) specifies that the Manager view has the same structure as the Employee class. The USING clause, USING MANAGER-ID, specifies that the key for the view is the value of the field Manager ID (a real field in the database, not a virtual field). For each employee occurrence, an occurrence of the Manager view is created, with the data (id number, employee name, etc.) for the manager of that employee. The second DEFINE statement (line 20 in the query) is used to define the Manager Name virtual field like the existing Employee Name field (see "Using Virtual Fields" on page 52-6). The value of the Employee Name field in the MANAGER view is assigned to the Manager Name virtual field in the PRINT statement. The query produces the following report:

52-12

Chapter 53 Sending Query Output to a Data Entry Form

Use the EDIT statement to direct the output of a query to a data entry form:

The output of a query directed to a data entry form can be manipulated to update the database and/or used further in an application flow. The data entry form is called a query output form. Other query features (e.g. using virtual fields, parametric queries etc.) can be incorporated into an output form query.

53.1 Writing a Query Using a FORM

To direct output to a query output form, you need the following:

An operation definition containing the fields you want to see. The operation can be defined via the Operation Definition (100401) form. A entry data form defined to display that operation with the necessary form options assigned in the definition of the data entry form. The data entry form is defined using the Form Definition (100675) form. A query defined with the number of the data entry form entered in the Query Definition (100230) form. The data entry form number is entered into the Output Form textbox.

You can utilize existing operation and data entry form definitions.

53-1

53

Sending Query Output to a Data Entry Form Writing a Query Using a FORM

Example:

To look at the employee salaries online:

The number of the output form where the output appears is specified in the Output Form textbox. If an EDIT statement is not defined, the output can only be viewed. (See "Using the EDIT Statement to Manipulate the Output" on page 53-4.)

The output form must be defined before running the query.

The query does not contain an output statement to specify the fields that you want displayed. When the query is executed, the output form specified in the Output Form textbox is used to identify the operation used for the output, and then displays the output based on the fields in this operation.

53-2

Sending Query Output to a Data Entry Form Customizing the Output Form

When you execute the query the output form is displayed instead of a listing:

If output from the query contains more occurrences than can fit on one physical form, form after form of output is filled up, fitting as many occurrences as possible on each form until all the occurrences have been displayed. You can scroll forwards and backwards through the list of occurrences using the Forward and Backward system actions.

53.2 Customizing the Output Form

You can modify an output form definition to customize the display of the query output. For example, you can hide fields so that they are not displayed, even thought they are part of the query output.

53.3 Using the Query Output Form as Part of a Flow

An application can be built with queries as part of the application flow. Via this flow the end user can transparently run queries. A menu can include the query output as one of its menu options. The menu option can be a query that produces a listing or an output form. In either case, the query is specified for the menu option in the BLP

53-3

53

Sending Query Output to a Data Entry Form Using the EDIT Statement to Manipulate the Output

Command editdrop option (Options tab>Actions Invoked category) of the Menu Definition (100601) form:

You can define private function buttons for an output form that, when clicked, access other forms in the application flow.

53.4 Using the EDIT Statement to Manipulate the Output

Use the EDIT statement to manipulate the query output and to update the data stored in the database:
EDIT <oper> FOR <type>.

oper type

The name of an operation that is included in the output form. One of the types listed below: If you do not specify any <type> in an EDIT statement, SELECT is the default. If you do not have any EDIT statement at all in a query using an output form, an EDIT statement is assumed, in which the <type> is SELECT and <oper> is the operation name corresponding to the operation specified in the output form definition. Thus, the query described in "To look at the employee salaries online:" on page 53-2 is equivalent to the following query:

for all employee. edit employee-salary for select.

53-4

Sending Query Output to a Data Entry Form Using the EDIT Statement to Manipulate the Output

EDIT Types
SELECT Allows you to view the values of the fields in the operation occurrences on the output form, but not to make any changes to the values in the database. An asterisk (*) is displayed in the Operation Code field. This is the default. Allows you to view the values of the fields in the operation occurrences on the output form and to enter new occurrences to the database via the output form. You cannot to make any changes to existing values in the database. An I is displayed in the Operation Code field. Allows you to view the values of the fields in the operation occurrences on the output form, and to change the values of any of the fields, but not to delete any old occurrences or enter any new occurrences. A C is displayed in the Operation Code field. Allows you to view the values of the fields in the operation occurrences on the output form, and to delete any of them from the database, but not to insert any new occurrences or change any old ones. A D is displayed in the Operation Code field. A combination of type 2, 3, and 4 above. That is, you can view the values of the fields in the operation occurrences on the output form, insert new ones and change and delete old ones. An X is displayed in the Operation Code field (instead of a C if MODIFY is used). A combination of type 2, 3, and 4 above. That is, you can view the values of the fields in the operation occurrences on the output form, insert new ones and change and delete old ones. A C is displayed in the Operation Code field (instead of an X if UPDATE is used).

INSERT

CHANGE

DELETE

UPDATE

MODIFY

Example of an EDIT Statement

You can look at the employee salaries online and make changes to the information displayed.
for all employee. edit employee-salary for change.

53-5

53

Sending Query Output to a Data Entry Form Using the EDIT Statement to Manipulate the Output

When you execute the query the output form is displayed:

The output for this query is the same as the output shown for "To look at the employee salaries online:" on page 53-2, except that instead of an * in the Operation Code field for each operation occurrence, there is a C, signifying that the data can be changed. Each change that you make on the form is stored in the database. The key field must be defined in the operation in order to update an occurrence. If you do not want the key field to appear in the output form, include it in the operation definition and ignore it in the form definition (via the Ignore option on the Field in Block form).

Selectively Displaying the Query Output in an Output Form

You can specify in a query containing an EDIT statement that you want certain fields to appear on the output form with their values taken from the database and other fields to appear empty. To do this, specify the fields that are to appear empty in the EDIT statement and follow these fields with a USING clause specifying the fields that are to appear with values from the database. All fields not specified in the USING clause are displayed on the form empty, allowing you to enter new values. Any values that you enter override the values stored in the database. If you do not enter a value, then the original value is kept (i.e. it is not overridden with an empty value). Example: To change the salaries of employees, when you do not want the old salaries displayed:
for all employee. edit employee-salary for change using employee-name hire-date.

53-6

Sending Query Output to a Data Entry Form Using the EDIT Statement to Manipulate the Output

When you execute the query the output form is displayed:

If you do not enter a value in to the Salary textbox for a particular employee, that employee's salary remains unchanged.

Displaying Calculated Values in an Output Form

Use a WITH clause in the EDIT statement to display calculated values for specific fields. In the WITH clause, specify the fields that you want to appear on the output form with values assigned by statements in the query (including values assigned by the WITH clause itself). All other fields that are displayed on the form are displayed with their values taken from the database. Example: To display the salaries of employees after a 10% increase:

for all employee. edit employee-salary for change with new-salary as salary * 1.1. define new-salary like salary.

In order to define a new value to the Salary textbox in the EDIT statement, a DEFINE statement was needed to create the New Salary virtual field. (See "Using Virtual Fields" on page 52-6 for details about virtual fields.) Adding 10% to the salary results in salary values with fractional parts, increasing the output length of the field. The following message is displayed when the query is executed:

53-7

53

Sending Query Output to a Data Entry Form Including More than One Block in an Output Form

Clicking OK results in the output form being displayed:

The new (calculated) salaries are displayed on the output form in the Salary field, but they are not yet updated in the database. To update a salary in the database move the pointer to the line to be updated and overtype the C in the Operation Code field. Press <Enter>. The original salary remains stored in the database for every other employee, whose occurrence is not manually updated.

The key field must be defined in the operation in order to update an occurrence. If you do not want the key field to appear on the output form, include it in the operation definition and ignore it in the form definition (via the Ignore option on the Field in Block form).

53.5 Including More than One Block in an Output Form

You can define more than one block in an output form. Each block in the output form has its own operation. In the query each operation is referred to in a separate EDIT statement. An output form defined with two blocks requires a query with two EDIT statements, one per block.

Remember to specify the operation name in each EDIT statement. The operation name determines which block of the output form is used by the EDIT statement.

If an EDIT statement is missing, the default EDIT statement (FOR SELECT) is used.

53-8

Chapter 54 Extracting Raw Data to an External File

Use the EXTRACT statement to extract data from the database to an external file where it can be used later as input to other programs or software packages:

The EXTRACT statement generates an external file of composites on Business Integrity Server. The filename is FILE and the filetype is EXT. This file contains all the occurrences of the extracted fields. The generated operation file overwrites any existing file with the same name (FILE EXT). Example: To extract a list of the about-to-retire employees to be used as input to an external software package (e.g. to calculate the pension money owed to each of these employees):
for all employee where birth-date < 01.01.40. print employee-name salary hire-date. extract employee-name salary hire-date.

In addition to the extracted file, you can receive a printed report with the same or different information. You can use the EXTRACT statement either with or without the PRINT statement.

When both EXTRACT and PRINT appear in a query, only one sort definition can be specified, either with the BY keyword in one of the output statements (PRINT or EXTRACT) or in a separate SORT statement.

The BY keyword appears before the Employee Name field in the PRINT statement. In both the report and the external file generated, the lines
54-1

54

Extracting Raw Data to an External File

are sorted by this field. The BY keyword could have been placed in the EXTRACT statement, instead of in the PRINT statement, with the same result. The external file, FILE EXT, can be seen via the 3270 emulation (refer to eMerge Applications via 3270-Display):
CARR GERALD FEILS CAROL HANSEN ZACHARY JOHNSON PATRICIA KRAUS JEFFREY LISTER MURIEL MARCH STEPHEN WELLER ALEXANDER 49500 9/12/88 24700 6/01/91 32900 5/07/90 7450010/12/87 42500 4/04/88 22700 2/12/87 3190011/12/89 41900 7/08/87

There are no delimiters between the field values in the external file. Before being able to use the EXT file as input to the BLP in batch (via the DBUPD procedure), you must enter your userid and password at the beginning of the file.

The field values appear in the external file in the order in which the fields appear in the EXTRACT statement. The structure of the file is determined by the output lengths for the fields contained in it. This file has the following structure: Field Name employee name salary hire date Total length Length (number of characters) 20 6 8 34

54-2

Chapter 55 Updating the Database Using Queries

Use an UPDATE statement to update data in the database:

You can perform an update either immediately, online, or by generating an external file of operations that can be used later as input to the BLP. The filename of the generated file is FILE and the filetype is TRAN. The generated operation file overwrites any existing file with the same name (FILE TRAN). To perform an update with an UPDATE statement, specify the update operation (INSERT, CHANGE or DELETE), followed by the name of the operation (<oper>) to be used for the update, followed by the list of fields (<field>) to be updated in the operation. The UPDATE statement generates an operation occurrence for each line of data output by the query. The structure of this occurrence is based on the structure of the operation definition specified in the UPDATE statement. The class specified in the FOR statement of the query must be the target class in the operation definition.

The query does not create the operation for you. You must insure that the operation exists before you run your query.

You can have any number of UPDATE statements in the same query.

55-1

55

Updating the Database Using Queries Updating Dates

55.1 Updating Dates

To update dates in the database you must specify the date in one of the following ways:

With periods for separators, for example 01.01.99 or 1.1.99 With quotes, for example 010199 (leading zeros must be given) With quotes and a valid separator, for example 1.1.99 or 1/1/99

55.2 Updating the Database Immediately

The keyword NOW instructs to perform an update online immediately, rather than creating a TRAN file to be used to update the database later. As soon as you run the query, each occurrence of the target class of the operation which meets the query criteria is updated. Using the NOW keyword does not result in a TRAN file, but immediately updates the database. When using NOW in an update statement, run the query with a PRINT statement and without the update statement first, to check the data to be updated, before running the updating query. Example: In the delete example on page 55-5, every occurrence of the Employee class in which the value of the Birth Date field is less than 1/1/1940 is deleted immediately from the database.

55.3 Changing Existing Data

Use the CHANGE keyword to change existing data. Example: To change the data stored about retiring employees to contain the position code and the division number reserved for pensioners (position code 16 and the division number 5):
for all employee where birth-date <01.01.40. change employee-retire using id-no position-code = 16 division-no = 5.

In this example Employee Retire is the name of the operation used for the update.

55-2

If the operation number is 10,000 or greater (i.e. 5 digits), insure that the following statement appears in the query: OPTIONS OPER-NO-LEN 5.

Updating the Database Using Queries Changing Existing Data

USING and WITH Keywords

The USING keyword appears immediately before the list of fields to be updated in the operation. These fields are the only field values that are included in the operation occurrences created by the query.

You must include all the key fields for the target class (ID No in this example) when using the USING keyword in an update statement.

Use the WITH keyword to automatically include all of the fields specified in the operation definition. See "The WITH Keyword" on page 55-5 for more details about using the WITH keyword.
Either WITH or USING must precede the list of fields in the update statement.

Assignment Expression
Fields that appear with assignment expressions (Position Code and Division No in this example) appear with their new values in the operation file. Fields that appear without an assignment expression (ID No in this example) appear with their old values, taken from the database, unless they appear with an assignment expression in some other statement in the query. A value can be assigned to a field only once in a query. The value is the value of the field in every statement in which the field appears in the query, regardless of which statement contains the assignment expression. The value of a field is changed only if it appears with an assignment expression in some statement in the query.

Resulting TRAN file

The operation file, FILE TRAN, is as follows:
33011 33011 33011 33011 33011 33011 33011 33011 3 10 13 15 16 20 22 28 5 5 5 5 5 5 5 5 16 16 16 16 16 16 16 16

Each line in the file begins with the number of the Employee Retire operation (i.e. 3301), followed by the operation code (in this case, 1, for change), followed by the fields in the order in which they appear in the
55-3

55

Updating the Database Using Queries Deleting Data

operation definition itself. The length of each field in the TRAN file is the same as the input length defined for the field in its field definition. The operations in the TRAN file are in fixed format. All the fields in the operation definition that are not included in the USING clause (e.g. Employee Name, Birth Date) appear as blanks in the operation occurrences in the TRAN file. The structure of the file is determined by the output lengths for the fields contained in it. This file has the following structure: Field Name operation no operation code id no division no birth date sex position code Total Length Length (number Value of characters) 4 1 5 3 6 1 3 43 3301 1 (blank) 5 (blank) (blank) 16 change operation (blank) value taken from database Note

employee name 20

The order of the fields in the update statement does not have to match their order in the operation definition. However the occurrences in the TRAN file are listed in the order in which they appear in the operation definition.

Before being able to use the TRAN file as input to the BLP in batch, you must enter a userid and password at the beginning of the file.

In addition to the TRAN file, you can receive a printed report with the same or different information. You can use the UPDATE statement either with or without the PRINT statement. The report produced reflects the new values for the fields updated in the CHANGE statement, even though they are not updated until the TRAN file is run as input for the BLP.

55.4 Deleting Data

Use the DELETE keyword to delete existing data.

55-4

Updating the Database Using Queries Inserting Data

Example: database:

To delete the data stored about retiring employees from the

for all employee where birth-date <01.01.40. delete now employee-retire using id-no.

The employees are deleted from the database. For details of the NOW keyword see "Updating the Database Immediately" on page 55-2.

55.5 Inserting Data

Use the INSERT keyword to insert new data. Example: To start a new project whose project number is 71 and to assign all the employees who worked on project number 50 to work on the new project: for all project-employee where project-no = 50. insert new-project with projno =71 id-no. define projno like project-no. Project Employee is the name of the class which contains information about which employee is working on which project, and New Project is the name of the operation which updates this class. Each new occurrence of the Project Employee class will have the value 71 for the Project No key field, and all the rest of the fields, including the second key field ID No, will have the same values as they have for the corresponding class occurrence with project number 50. A virtual field Projno is defined to be like the field Project No that appears in the WHERE statement. This new field name is the one that is used in the INSERT statement. (Refer to "Using Virtual Fields" on page 52-6 for details about defining virtual fields.)

If you need to use the same field in both the WHERE statement and the UPDATE statement, define a virtual field, with a new name, like the field used in the WHERE statement. Use the virtual field in the UPDATE statement.

The WITH Keyword

Values appear for all of the fields in the operation definition that have values in the database, even if they are not mentioned in the update statement. This is due to the WITH keyword in the INSERT statement.

55-5

55

Updating the Database Using Queries Inserting Data

The WITH keyword indicates that all of the fields in the operation definition are included in the operation occurrences created by the query (compare this with the USING keyword on "USING and WITH Keywords" on page 55-3).

The Resulting TRAN File

The operation file, FILE TRAN, is as follows:
4002 4002 4002 4002 4002 4002 4002 4002 4002 71 71 71 71 71 71 71 71 71 1 5 22 28 29 32 33 36 40 5036 2018 4530 6048 5018 7536 8030 9020

Fields included in an UPDATE statement with assignment expressions (Projno in this example) appear with the new values that are specified in the statement. All of the other fields in the operation, including those mentioned without assignment expressions (ID No in this example), appear with their old values from the database. This file has the following structure: Field Name operation no Length (number Value of characters) 4 4002 (blank) represents an insert operation 71 nnnnn value taken from database nnn nnn nn value taken from database value taken from database Note

operation code 1 project no id no role months Total Length 4 5 3 2 22

percent of time 3

Data for id no, role and percent of time is taken directly from the database. For example, in the first occurrence the ID No is 1, the Role is blank, the Percent of Time is 50 and the Months is 36.
55-6

Updating the Database Using Queries Maintaining Database Integrity With an UPDATE Statement

No values appear in any of the operation occurrences for the Role field because there are no values stored for Role in the database. In the last operation occurrence for the employee, whose id number is 40, blanks appear for the Percent of Time and Months fields for the same reason. When the TRAN file is input to the BLP, the new project whose project number is 71 is stored in the database with all of the employees assigned to it that were assigned to project number 50. In this case, nine new occurrences of the Project Employee class are created with one INSERT statement.

55.6 Maintaining Database Integrity With an UPDATE Statement

Use the update statement to download data to an operation file for safekeeping when making changes to the database structure. Data stored in eMerge that is affected by the restructuring could possibly be corrupted. By storing the data in an operation file you can reload it to the restructured database. 1 Store the data in an operation file, via a query, using the CHANGE statement. 2 Delete the data in the database. You can use the delete statement to delete the data. 3 Make the structural changes to the database. 4 Edit the operation file, if necessary, to conform to the new structure, using a text editor. 5 Run the operation file in batch to update the database.

55-7

55

Updating the Database Using Queries Maintaining Database Integrity With an UPDATE Statement

55-8

Chapter 56 Using SQL in a Query

You can incorporate SQL statements within queries when you work with SQL. See DBMS Adapter Reference for details about interfacing to SQL databases. Incorporate SQL into your queries for any of the following reasons:

To query SQL data and include the output in an eMerge session. To combine data from SQL and non-SQL databases. To utilize prior familiarity with SQL. If you are accustomed to producing your reports with SQL, then with only a minimum query knowledge, your SQL reports can be part of your eMerge application. Full SQL syntax is supported. To combine query editing facilities with SQL data extraction.

Different versions of SQL can produce different results when included in a query. For example, the decimal precision algorithms used can be different, causing different results when arithmetic calculations are requested in a query. A query supports arithmetic calculations having numbers containing up to 15 digits. Calculations using or resulting in numbers having more than 15 digits cause an error message to be issued. If you have old queries, for which the DEFINE SQL statement must be processed by eMerge, follow the instructions in the migration chapter of the eMerge installation guide.

56.1 Defining an SQL Query

The SQL query accesses an SQL database directly. You do not need to consider mapping as in the eMerge DBMS Adapter.

56-1

56

Using SQL in a Query Defining an SQL Query

FOR Statement
The SQL query is referenced by the FOR statement. The FOR statement must be the first statement, as in a standard query.

DEFINE Statement
The scope of reference for the query is determined by the DEFINE SQL statement, which contains an SQL SELECT statement.

SELECT Statement
The SQL SELECT statement may contain nested SELECT statements, in conformance with SQL syntax. Columns in a nested SELECT statement are internal to SQL and are not part of the query context.

Including Queries
Once you have defined an entire SQL query (from DEFINE... SELECT... to ;), you can include the entire SQL query as part of another query by using the %INCLUDE clause. SQL query 488
DEFINE... SELECT........;

SQL query 500

%INCLUDE query 488 %INCLUDE query 489

SQL query 489

DEFINE... SELECT........;

In addition, the included query need not be a full, executable query. It can be part of a query or even part of a statement. That is, the included query is the equivalent of a macro or subroutine that you include into other SQL queries. You do this by defining a string of text as a query (e.g. query 501 below) and using the %INCLUDE clause to include the query containing the string in any other SQL query.

56-2

Using SQL in a Query Defining an SQL Query

SQL query 502 SQL query 501

where value=20 DEFINE.... SELECT..... %INCLUDE query 501 ....;

Query View
When an SQL query is executed, it produces a query view which contains SQL data. The view can be accessed by standard query statements (e.g. the PRINT statement). Only selected SQL columns (or their corresponding names, i.e. fields with which they are coupled) can be referenced by query statements or other SQL SELECT statements in the query.

Example
Example: The following is a small but complete SQL query.
for all mysql define sql query sqll select empno, empname, empsalary from emptbl; print empno, empname, empsalary.

An SQL query can be referenced only from within its own query, unless it is part of an included query. The keyword QUERY in the DEFINE SQL statement is optional.

Dynamic Mode and Static Mode

Set the value of the I/O Module Prefix field to DYN so that the query can be executed immediately. For testing purposes, you can develop queries incorporating SQL in dynamic mode (the value DYN is set). In production, run queries in static mode. See "Mode of ExecutionDynamic vs. Static" on page 56-14.

56-3

56

Using SQL in a Query The DEFINE SQL Statement

SQL Query Name

The name you use to identify the SQL query can have a maximum length of 16 characters. It must begin with a letter, and may contain letters, digits, embedded blanks or underscore (_) characters. The name must be unique within its own query and across any higher level queries that include it. The behavior differs depending if the name is, or is not, identical to the name of an eMerge data object (i.e. concept, class, or constructor): If the name is identical to the name of an eMerge data object, then the query is run for each occurrence of the eMerge data object. If the name is not identical to the name of an eMerge data object, then the query is only run once.

56.2 The DEFINE SQL Statement

Use the DEFINE SQL statement to incorporate SQL SELECT statements (i.e. SQL queries):

The DEFINE SQL statement is made up of two clauses: <sqlviewclause> <selectclause> This contains eMerge definitions. This is the SQL SELECT statement.

Syntax Rules
The following syntax rules apply to the DEFINE SQL statement: 1 The <selectclause> must start on a new line. 2 Unlike other query statements, the DEFINE SQL statement ends with a semi-colon and not with a period. 3 Comment lines start with slash-asterisk (/*) and end at the end of the line. 4 You can place comment lines or blank lines between the <sqlviewclause> and the <selectclause>.

56-4

Using SQL in a Query The DEFINE SQL Statement

5 At the end of any line of text of the <selectclause> or the <sqlviewclause>, you can place a comment starting with slash-asterisk (/*) and ending at the end of the line. 6 The <sqlviewclause> or the <selectclause> may be split among any number of lines. You may not split a keyword or token between lines. 7 Multiple blanks are allowed between keywords and tokens in the <sqlviewclause> and the <selectclause>. 8 The <sqlviewclause> is case insensitive. Uppercase and lowercase are equivalent, because everything is translated to uppercase. The <selectclause> is passed to the SQL DBMS, so you must use the case expected by the DBMS. This applies mostly to the names of columns and tables (tokens).

<sqlviewclause>
This clause contains eMerge definitions. It tells eMerge what to do with the <selectclause>. For instance, if there is a code element or not, which logical DBMS is used, etc.

<sqlqueryname> OPTIONS

The name of the SQL query. There is no significance to the order in which the options are specified. Each option is specified as KEYWORD=value. This cannot be split over more than one line. There must be no blanks before or after the equals sign (=). Options may be separated by one or more spaces.

CODE=

For operating systems in which the I/O module is generated in Assembler, this option specifies whether or not to generate code elements for the sub query.

56-5

56

Using SQL in a Query The DEFINE SQL Statement

YES NO

Generate code elements. By default, code elements are generated. Do not generate code elements.

This option is not relevant under HP-UX or i5/OS and it is ignored if provided. In these environments the I/O module is written in C which does not use code elements. SYNTAX= This option specifies how the <selectclause> of this DEFINE SQL statement is provided: SQL The <selectclause> is passed to SQL exactly as it appears in the DEFINE SQL statement, with no formatting performed by eMerge. This is the default, unless the eMergeSyntax option is assigned for the DBMS. OP The <selectclause> is provided in the old syntax, where eMerge must parse and format it before passing it to SQL. It is recommended that you switch over to the new system of specifying the <selectclause>. Future releases of eMerge will not necessarily support the old eMerge format. LDI= Specify the Logical DBMS ID for this <selectclause>. This points to the DBMS profile. To specify a Logical DBMS ID for the whole query, specify it in the Logical DBMS ID field in the Query Definition (100230) form. If a Logical DBMS ID is not specified, the default Logical DBMS ID defined for the database is used. If a default Logical DBMS ID is not specified, the Logical DBMS ID defined in the DBMS Profile Definition form is used. For an explanation of the Logical DBMS ID and the DBMS profile, see the DBMS Adapter Guide. CURSOR= Indicates the type of SELECT. If the operation method is findByKey, then <cursornumber> is 0. Otherwise, <cursornumber> is 1.

<selectclause>
This is the SQL select statement. The actual text of the statement must adhere to standard SQL language syntax (refer to the SQL literature). If you do not specify the table CREATOR in the SELECT statement, the creator default value is assigned.

56-6

Using SQL in a Query Defining More than One SQL Query in a Query

56.3 Defining More than One SQL Query in a Query

Two or more eMerge objects can be implicitly joined in a query via common fields. If data is stored in an SQL DBMS and accessed via DBMS Adapter, standard query statements relate to the data as they do to data stored in the eMerge database. In SQL, you can explicitly relating a column from one object to a column in another object. Use the WHERE clause of the SQL SELECT statement, for example:
define sql query mysql select empno, empname from emptbl a, depttbl b where (a.empno = b.empno) and (depttbl= 100);

Join an SQL table with a native eMerge (or non-SQL) object in the same way: they are not implicitly joined as two native eMerge objects are. If you need to refer to a field outside of the initial context generated by the FOR statement, and there is no connection between the field and any of the fields in the context, use the SQL WHERE clause in the SELECT statement. The USING clause cannot be used in SQL queries.

56.4 SQL Parametric Queries

You can use query parametric fields in an SQL query. Two types of parametric fields can be used in the select statement of an SQL query:

User Parameters (@) Query Context Parameters (:)

If an eMerge field is to be included in an SQL query, it must be a parametric field, unless it follows the keyword AS. For example, if you want to select SQL data, based on the value of an eMerge field, the eMerge field must be defined as a parametric field (the eMerge field appears in a WHERE conditional of an SQL SELECT statement) You can use any number of parameters in an SQL query. User parameters and context parameters can be used in the same query. The parameter name must identify a real eMerge field and not a virtual field defined in a query. The field is used as a template to describe the parameter. The field identified is not restricted to the query context; it can be any field defined in eMerge.
56-7

56

Using SQL in a Query SQL Parametric Queries

If the name of a parametric field used in an SQL query is not unique, it still can be referenced by identifying it via its table:
<field-name> of <table-name>

User Parameters
User parameters are standard query parameters. They are identified in the query by the at-sign (@) prefix. User parameters in an SQL query are handled as any other query user parameters. User parameters must be unique eMerge fields. They cannot be prefaced with a qualifier. Example:
define sql query mysql select empno, empname from emptbl where empno > @empno;

In the above example, the user is prompted to assign a value to the EMPNO field prior to execution of the query. This value is substituted in the SQL statement and passed on to SQL for execution. If the field EMPNO is defined in eMerge, the field name may be used as the parameter name, i.e. EMPNO appears as the subject and object of the WHERE clause. Using EMPNO as a parameter simply means that the parameter is characterized by EMPNO. Though EMPNO is used as a parameter, the value assigned by the user to that parameter does not change the value of EMPNO in the database. If the field EMPNO is not defined in eMerge, some field must be defined which can be used as a template for the user parameter. The above example assumes that EMPNO is defined in eMerge.

Context Parameters
Context parameters are fields to which values have been assigned during the processing that preceded the execution of the SQL query. Context parameters are preceded by a colon (:). The assigned value can be obtained directly from the database, by computation, or assigned during a previous SQL query. eMerge global fields (e.g. Current Time) may also be used as context parameters. Example:

56-8

Using SQL in a Query Sample Queries

define sql query mysql select empno, empname from emptbl where empno > :empno;

In the example above, EMPNUM is a field that is assigned a value during the processing that precedes the execution of the SQL query named MYSQL. EMPNUM is either a field defined in eMerge, or a virtual field defined in the query.

56.5 Sample Queries

The following sample queries illustrate the use of SQL queries.

Case 1: Parameters and Multiple SQL Queries

In this example, the SQL Query SQL1 is executed first since it is specified in the FOR statement. SQL Query SQL2 is automatically executed following SQL1.
... FOR ALL SQL1. ... DEFINE SQL QUERY SQL1 SELECT PARTNUM, PARTNAME, PARTQTY FROM INVENTORY WHERE PARTQTY < @MINQTY; ... DEFINE SQL QUERY SQL2 SELECT SUPPLIERNAME, SUPPLIERCODE, FROM SUPPLIERS WHERE SUPPARTNUM = :PARTNUM; ... PRINT PARTNAME PARTNUM PARTQTY SUPPLIERNAME SUPPLIERCODE. ...

Minimum quantity MINQTY is a user parameter whose value is interactively obtained from the user. The set of values for PARTNUM is returned from Query SQL1 and used as input for Query SQL2. In query SQL2 :PARTNUM is a context parameter. Notice that in Query SQL1 PARTNUM is specified without a colon (:), and in query SQL2 it is preceded by a colon (:). This is because in query SQL1 it signifies the name of an SQL column, whereas in query SQL2 it
56-9

56

Using SQL in a Query Sample Queries

signifies an eMerge context parameter. Since the PRINT statement is not part of the SQL query, partnum without the colon (:) represents an eMerge field. Note that it is incorrect to specify a second FOR statement for query SQL2. However, it is syntactically correct (though in this example it is illogical) to say FOR ALL SQL2 instead of FOR ALL SQL1. The SELECT in query SQL2 is executed for each resultant row produced by the select of query SQL1. The report produced by the PRINT statement shows the join of the data of two SQL tables.

Case 2: Combining SQL Queries

The nearly logically equivalent of the above example could be accomplished with just one SQL query, in the following way:
... FOR ALL SQL3. ... DEFINE SQL QUERY SQL3 SELECT SUPPLIERNAME, SUPPLIERCODE, SUPPARTNAME, SUPPARTNUM FROM SUPPLIERS WHERE SUPPARTNUM IN (SELECT PARTNUM FROM INVENTORY WHERE PARTQTY < @MINQTY); ... PRINT SUPPARTNAME SUPPARTNUM SUPPLIERNAME SUPPLIERCODE. ...

SQL query SQL3 of Case 2 essentially accomplishes the same result as SQL queries SQL1 and SQL2 of Case 1. The difference is that in Case 1, the part name (PARTNAME) and part number (PARTNUM) are taken from the inventory SQL table, whereas in Case 2, they are taken from the suppliers SQL tables (SUPPARTNAME, SUPPARTNUM). It might appear redundant to have PART NAME in both the inventory and supplier SQL tables, but this allows the customer to use his own part names which might differ from the names the supplier uses, e.g. hammer instead of 14 oz. Claw Hammer. In Case 2 the part name (PARTNAME) and part number (PARTNUM) cannot be taken from the inventory SQL table since that table is part of a nested SELECT statement. Columns from a nested SELECT statement are internal to SQL and are not known to a query. In other words, nested select columns are not coupled with eMerge fields nor are they part of the query context.
56-10

Using SQL in a Query Sample Queries

The advantage of nested select statements is that they allow DB2 or SQL/DS to optimize the search path while isolating the query from data that does not concern it and requiring fewer SQL DBMS calls. Thus, in Case 2, SUPPARTNUM is used in the PRINT statement rather than PARTNUM. However, a more significant difference exists between the two cases. Case 2 does not allow for selection of columns from the inventory SQL table. Therefore PARTQTY is not retrieved and cannot be printed.

Comparison of Case 1 and Case 2

While the Case 2 type approach (one SQL query) may limit the application data retrieved, it is normally more efficient than the Case 1 approach (two SQL queries). This is because the intermediate SQL resultant SQL tables are handled at the source (in the SQL DBMS), rather than in the query, allowing for global optimization instead of local optimization. Combining the two SQL queries into one, reduces the amount of data retrieved from the SQL database and transferred to eMerge. It also decreases the size of the working set (intermediate data) that has to processed.

Case 3: Merging and Optimizing Case 1 and Case 2

To achieve all the results of Case 1 and still maintain most of the efficiency of Case 2, the following SQL query could be used:
... FOR ALL SQL4. ... DEFINE SQL QUERY SQL4 SELECT SUPPLIERNAME, SUPPLIERCODE, SUPPARTNAME, SUPPARTNUM, PARTQTY FROM SUPPLIERS, INVENTORY WHERE SUPPARTNUM IN (SELECT PARTNUM FROM INVENTORY WHERE PARTQTY < @MINQTY) AND SUPPARTNUM = PARTNUM; ... PRINT SUPPARTNAME SUPPARTNUM PARTQTY SUPPLIERNAME SUPPLIERCODE. ...

In this case, even though only one SQL query is used, all the data retrieved in Case 1 can still be retrieved. This is accomplished by using the inventory SQL table in both the nested select and the main select.
56-11

56

Using SQL in a Query Sample Queries

Case 4: Joining eMerge and SQL Data

The following is a simple SQL query application intended to demonstrate the following concepts:

Joining eMerge and SQL data Context parameters in an SQL query Joining eMerge and resultant SQL data in a report
INVENTORY
) and eMerge minimum quantity control constructor (called

The application consists of an SQL inventory table (called

A different minimum quantity is assigned to each type of part. This application requires a query that produces a report showing how many of each part must be reordered to restock the inventory so that minimal quantities are maintained. SQL Query The following SQL query is used to list all the data in the inventory table: part number, part name and part quantity:

MINQTIES

). The eMerge constructor is used to maintain a minimum quantity of parts in the inventory.

for all sqls. define sql query mysql select partno, partname, partqty from inventory; print partnum partname partqty.

Resulting Report

The query produces the following report:

Control Concept

The following shows the contents of the eMerge minimum quantity control concept: PARTNUMBER 100 200 300 500 700 500 MINQTY

56-12

Using SQL in a Query Sample Queries

SQL query

The following SQL query is used to show which parts in the inventory table have fallen below their allowed minimum quantity, and therefore must be reordered:

for all minquantities. define sql query mysql select partno, partname, partqty from inventory where (partnum =:partnumber) and (partqty < :minqty); print partnum partname partqty.

In the above query, the eMerge control concept (MINQTIES) is initially selected, producing an intermediate resultant concept. It contains fields (columns) called PARTNUMBER and MINQTY. The values for these fields in the intermediate resultant concept are passed to the SQL query as context parameters in the WHERE clause. Resulting Report The query produces the following report:

As shown above, the final result concept has only one entry. This is because there is only one part in the inventory table whose quantity is less than the corresponding control concept minimum amount. The report is the result of joining data of an SQL table with an eMerge concept. SQL Query The following is the same query as above, enhanced to also show the minimum quantity from the control concept in the report:

for all minquantities. define sql query mysql select partno, partname, partqty from inventory where (partnum =:partnumber) and (partqty < :minqty); print partnum partname partqty minamt as minqty using partnum. define minamt like minqty.

This query differs in its last two lines. A virtual field (MINAMT) is defined like the MINQTY field of the control concept. The corresponding minimum
56-13

56

Using SQL in a Query Mode of ExecutionDynamic vs. Static

quantity from the control concept is joined to the final resultant report. This is done in the PRINT statement, by the USING clause. This, in effect, uses PARTNUM from the final resultant SQL table as the key to the eMerge control concept. Resulting Report The query produces the following report:

In this report, the minimum quantity from the control concept is shown as well, demonstrating how the results of an SQL query can be joined with native eMerge data in a single report.

56.6 Mode of ExecutionDynamic vs. Static

The SQL statements in the query may be executed in either dynamic mode or static mode. The mode of the query is determined by the value entered into the I/O Module Prefix textbox in the Query Definition form. Dynamic mode is set by entering the value DYN into the field. Any other value indicates static mode. Dynamic mode is more convenient, since it can be executed immediately, without having to leave the eMerge session and generate an I/O module. On the other hand, a dynamic query runs more slowly than a static query. During development and testing, it is normally more convenient to use dynamic mode. In a production environment it makes sense to use static mode for predefined queries and dynamic mode for ad-hoc queries.

Dynamic Mode
Dynamic mode means that all processing (including preprocessing and binding) of SQL statements is done at run time. Once a dynamic query is entered and successfully compiled, it can be executed immediately. Dynamic mode eliminates the intermediate step of generating an I/O module. When working in dynamic mode, each SQL select statement requires a dynamic path in the System I/O module. Therefore, the number of
56-14

Using SQL in a Query SQL I/O Module

dynamic paths defined in the System I/O module should be large enough to accommodate the largest SQL query, i.e. the query with the greatest number of SQL statements. Naturally, this will vary, but typically four or five dynamic paths should be sufficient. If not enough dynamic paths are defined, an error message is received. If this happens, ask the Administrator to increase the number of dynamic paths and regenerate the System I/O module. Then rerun the query. The number of dynamic paths is usually defined by the Administrator as part of the DBMS Adapter setup. It is defined in the CT database. It is set in the Paths field in the SQL Dynamic groupbox in the SQL DBMS Definition (23407) form. This form is described in the DBMS Adapter Reference.

Static Mode
Static mode means that the SQL statements are preprocessed before run time. Queries which contain SQL queries and use static SQL require an additional step following query compilation. The eMerge SQL Access Program (referred to as the I/O module) must be generated for such queries. This program performs the actual select against the SQL database. The I/O module is generated, assembled and link-edited in batch, outside the eMerge session. This must be done after the query is compiled and before the query is executed. Each time a query is changed and recompiled, its I/O module must also be regenerated. That is, the I/O module must be kept in sync with the query it services. A query which was compiled after its I/O module was generated will not execute, (the appropriate message is received). If the definitions of the eMerge fields used in the query are changed, the query may have to be recompiled. For exact criteria refer to the DBMS Adapter Guide.

56.7 SQL I/O Module

For details about I/O modules, refer to the DBMS Adapter Guide. A dynamic SQL query utilizes the System I/O module, which already exists and does not need to be generated after query compilation. If you are working in dynamic mode, you can skip this section.

56-15

56

Using SQL in a Query SQL I/O Module

The I/O module

The I/O module is an eMerge program that accesses an SQL database on behalf of one or more eMerge databases. From the point of view of the SQL DBMS, the I/O module is simply an application program that calls the SQL DBMS. An eMerge database may have several different I/O modules attached to it to handle different SQL interface applications. These are called User I/O modules. An eMerge database which includes an SQL database, always has one special I/O module attached, which is referred to as the system I/O module. The system I/O module handles eMerge system calls to SQL. It is also the default I/O module used when no user I/O module is specified for an application. An I/O module contains static SQL statements generated by eMerge. A static SQL query results in a set of SQL statements in an I/O module, which must be generated after query compilation. A single I/O module can include the SQL statements for both queries (which contain SQL queries) and SQL interface applications. The I/O module is a program generated outside an eMerge session by running an eMerge utility. Each time a query is compiled, its I/O module must also be regenerated, otherwise the query cannot execute. The I/O module must be kept in sync with the query it services. If definitions of eMerge fields used in the query are changed, even though the query remained the same, the query may have to be recompiled. If the query is changed, even though the SQL query definition remains the same, it is still necessary to regenerate the I/O module, since the query must be recompiled.

Multiple I/O Modules

There can be several I/O modules for an eMerge database, each supporting subsets of the database (individual applications or individual queries). Multiple I/O modules are distinguished and referenced by their unique names; the prefix is user-assigned. All the query SQL views of one query are contained in one I/O module, i.e. the query is the smallest unit of division. Assigning queries to different I/O modules is application-dependent and is done at the users own discretion. For example, an installation may choose to group its accounting queries into one I/O module and its personnel queries into another.

56-16

Using SQL in a Query Linking a Query to an I/O module

One I/O module may combine SQL calls for several queries and physical mapping records (SQL Interface Tables). That is, an eMerge constructor that interfaces to SQL and SQL queries can both be processed by the same I/O module.

56.8 Linking a Query to an I/O module

For each query, an I/O module name prefix may be specified. Specifying an I/O module prefix, assigns the query to that I/O module. The I/O module name prefix is entered from the Query Definition form. The name of the I/O module is specified in the I/O Module Prefix textbox. If DYN is entered as the I/O module prefix, it indicates a dynamic SQL query. The query is automatically assigned to the System I/O module. Dynamic queries can be executed immediately after compilation; no I/O module generation is necessary. When a query is assigned to a particular I/O module, the query is included with the I/O module when that I/O module is generated. I/O modules of other names will skip over that query. If no I/O module prefix is defined, the System I/O module is used by default. The System I/O module is named in the System Name field of the I/O Module subgroupbox in the SQL DBMS Definition (23407) form (in the Catalog (CT) database).

56-17

56

Using SQL in a Query Linking a Query to an I/O module

56-18

Chapter 57 Advanced SQL Queries

This section contains advanced material. Use it selectively, depending on your needs and the complexity of your application. There are two ways to pass a select clause to SQL in a query: the eMerge method the SQL method Some topics discussed in this chapter apply only to the eMerge method.

57.1 SQL Query Processing in the eMerge Method

During query compilation, SQL queries are separated from the non-SQL text. The result, which is a pure SQL query, is processed using standard SQL PREPARE and DESCRIBE commands.
PREPARE is an SQL operation that dynamically prepares an SQL statement for execution. DESCRIBE is an SQL operation that produces a descriptor table for the output of a PREPARED SQL statement. PREPARE checks the validity of the supplied SQL SELECT statements. If SQL syntax errors are found, the query compilation terminates with the appropriate SQL error code and error message.

The descriptor table produced by the DESCRIBE command is known as the SQL DESCRIPTOR AREA (SQLDA). The PREPARE and DESCRIBE operations and the SQLDA are described in IBM SQL Reference Manuals. Within a query, the prepared statement is always a SELECT statement. For every COLUMN selected in the prepared statement, the DESCRIBE statement returns the name, type, length, scale (for decimal columns) and a NULL indicator, showing if a column can have a null value or not. The structure of the SQLDA is stored in eMerge. It is used to generate the virtual fields (described in the next section) and the static SQL statements and queries in the I/O module.

57-1

57

Advanced SQL Queries Coupling Selected Columns in the eMerge Method

57.2 Coupling Selected Columns in the eMerge Method

The data values returned for selected columns in the SQL query must be categorized (data type, length, etc.) and temporarily stored. To do this, each selected column is coupled with an eMerge field which describes the SQL column. The eMerge field can be real (a field which has been defined in the eMerge knowledgebase) or virtual (a field defined only in the context). The set of coupled eMerge fields compose a virtual class, which corresponds to a row of the resultant SQL table. Each resultant, returned row logically corresponds to an occurrence of the virtual segment. A query can access and manipulate the virtual class. The coupling process takes place when the query is compiled. Field coupling is used for editing and formatting the data in query reports. The matching of SQL columns and eMerge definitions is especially useful when the query output is formatted via an output form. See Chapter 51, Basic Queries and Chapter 53, Sending Query Output to a Data Entry Form. During query compilation, a matching algorithm is used to couple the name of each selected column to an eMerge field. Information about the selected column is obtained from the SQL DESCRIBE operation. The following paragraphs explain the concepts involved in the coupling process. They are followed by a summary outlining the sequence of steps taken in the coupling process.

57.3 Implicit Matching

The eMerge concepts, corresponding to the tables in the SQL FROM clause, are searched for a field that matches each selected SQL column. That is, the search scope of implicit matching is the set of tables in the main SELECT statement. If an SQL column name matches an eMerge field name (or its synonym), they are coupled. If the eMerge field name is not unique, an error message is issued and query compilation terminates. If a column cannot be coupled to a real eMerge field, then a virtual field is automatically generated for coupling. The virtual field is assigned attributes like those returned by the SQL DESCRIBE operation. The scope of the virtual field is for the query execution only. See "Using Virtual Fields" on page 52-6.

57-2

Advanced SQL Queries Explicit Matching

57.4 Explicit Matching

SQL columns may be explicitly matched to a specific eMerge field (real or virtual) by using the AS clause. The syntax is as follows:

<sqlcol> the name of a column in the SQL table. This is referred to as the SUBJECT of the AS clause, or the AS SUBJECT. <field> the eMerge field to which the selected column is coupled. This is referred to as the OBJECT of the AS clause, or the AS OBJECT. The AS OBJECT need not name a real eMerge field. It can designate a virtual field, which is allocated based upon the characteristics of the SQL column. However, if it does name a real eMerge field, the eMerge field must be unique. If it is not unique, a compile error results. This can be avoided by qualifying the field name with the name of the segment to which it belongs. The eMerge knowledgebase is searched for a field matching the AS OBJECT, before a virtual field is allocated. Unlike implicit matching, the search is not limited to the tables in the query, i.e. the scope of search for explicit matching is wider than that for implicit matching. In fact, the field does not have to be included in any table to be matched. It is sufficient that it is defined as a stand-alone field in order to be coupled. If the AS OBJECT is qualified by a segment name, it must exist in that segment, or a compile error is received. When the as clause is used, the AS SUBJECT is not known to the query and is replaced by the AS OBJECT in the context of the query.

Example of Explicit Matching

... SELECT A,B,A+B AS SUMAB,D AS DATA1 ...

In this example, the third column (A+B) is explicitly matched to field SUMAB, and the fourth column (D) is explicitly matched to DATA1.

57-3

57

Advanced SQL Queries Qualified Field Names

When Explicit Matching must be Used

Explicit matching must be used in the following cases:

the SQL column selected is an expression (e.g. COLA/100). the SQL column name matches more than one eMerge field. the SQL column name differs from the corresponding eMerge field name or synonym. the SQL column name is longer than 16 bytes. two or more selected SQL columns have the same name (e.g. columns from two SQL tables).

Explicitly Defining Virtual Fields

If a virtual field is explicitly defined (using the DEFINE statement), it overrides a selected column, or the object of an AS clause of the same name.
... DEFINE A NUMERIC 6. DEFINE SUMAB NUMERIC 7. ... SELECT A,B,A+B AS SUMAB,D AS DATA1 ...

In this example, fields A and SUMAB have the characteristics of NUMERIC 6 and 7 respectively, regardless of their default definitions. Though the language permits doing this, there is no need for it, nor is it recommended. All explicit coupling should be done through the AS clause. If the user does use the override, it is his responsibility to assure that the data types are compatible. Otherwise, an error message is received.

57.5 Qualified Field Names

If the name of an explicitly matched field is not unique, it can still be referenced in the AS clause by qualifying the matched field using SQL format or query format.

57-4

Advanced SQL Queries Matching Columns via a Table Designator

SQL Format
If the name of an explicitly matched field is not unique, it can still be referenced in the AS clause by qualifying the matched field as follows: table-name.field-name Where table-name is a name of a table defined in eMerge, and field-name is a name of the field defined in the table. This type of qualification is only valid for eMerge fields in an SQL query. When referring to the object field of an AS clause outside of an SQL query (i.e. a PRINT or assignment statement), the qualifier must not be used. This is illustrated in the following example:
... SELECT EMPNO AS EMPLOYEE.ID FROM ... ... PRINT ID ...

In this example, Employee is the qualifying table name. ID is a field in the Employee table. Note that the PRINT statement refers only to ID and not to ID of Employee.

Query Format
Alternatively, the standard query format can be used in the AS clause: field OF class
... SELECT EMPNO AS ID OF EMPLOYEE FROM ... ... PRINT ID ...

57.6 Matching Columns via a Table Designator

An SQL SELECT statement can specify a table column by the column name alone, or as qualified by a table designator. A table designator (an SQL term) may be a table name, a view name, an alias name, a synonym or a correlation name. The table designator is primarily used to clarify ambiguous references, which can occur when more than one object table (designated in the SQL FROM clause), contains the same column name. It can also be used simply as a
57-5

57

Advanced SQL Queries Matching Columns via a Table Designator

shorthand substitute for ease and clarity. The use of a table designator in a SELECT statement has ramifications on the coupling process, as will be shown.
SELECT E.EMPNO, EMPNAME, CHILDNAME FROM PRSNL.TBEMP E, PRSNL.TBCHILD C WHERE E.EMPNO=C.EMPNO

In this example, the EMPNO column is found in both object tables (PRSNL.TBEMP and PRSNL.TBCHILD). Here the table designators used are correlation names (E and C). To avoid ambiguity, the EMPNO column name is qualified with E and C, which identify the PRSNL.TBEMP and PRSNL.TBCHILD tables respectively. Columns EMPNAME and CHILDNAME do not have table designators since they are unique in the object table set. When a table designator is supplied, the search for a coupling field is limited to the designated table, i.e. the eMerge concept that corresponds to the designated SQL table. In the cases shown so far, all tables in the SQL query are searched. Therefore, in the above example, only one eMerge table (corresponding to PRSNL.TBEMP) is searched to find a match for EMPNO (however, if both tables exist both corresponding tables are searched for EMPNAME and CHILDNAME). The practical ramification of this determines which field the query uses for coupling. This may be necessary to avoid unresolved references during query compilation. The field used for coupling affects how the SQL data is presented. Coupling to a virtual eMerge field means the data is presented as it would be through SQL. Whereas coupling to a real eMerge field allows for editing, e.g. determining the number of leading zeros to be suppressed. For an SQL column to be coupled to a real eMerge field, the eMerge field must belong to a table in the FROM clause of the SQL SELECT statement. If there is no real field which matches, the column will be coupled to a virtual field. If a field is qualified by a class name in the object of an AS clause, it must exist uniquely in the specified class. (Although an eMerge class cannot contain duplicate fields, a field may have a synonym identical to another field name, thereby causing it to be nonunique.) By understanding how coupling works, you can determine which field a column is coupled with and avoid ambiguous references. When no table designator is given for a column in the SELECT statement, the definitions for all object tables (in the SQL FROM clause), are scanned for a matching column. When no table designator is used,
57-6

Advanced SQL Queries Duplicate Columns from Different Queries

the selected column is uniquely defined in the SQL tables of the FROM clause. If a match is found, it is coupled to the SQL column. If the column cannot be matched, a virtual field is assigned.

57.7 Duplicate Columns from Different Queries

If two or more SQL queries are defined, and the same column is retrieved from both, i.e. it occurs in both tables, a duplication error can arise. This can be averted by using explicit matching. The problem of duplicate fields is most likely to occur when using select *. This results in all columns being retrieved. In some cases, this may result in a duplicate field being retrieved although it is not needed by the application. Selecting the specific columns, rather than using an asterisk, can resolve this.

57.8 Matching Unspecified SQL Names

If the name of the resultant SQL column is unspecified (e.g. if it is derived from an expression, such as the result of SELECT A+B), and if no explicit matching has been defined (via the AS clause), eMerge replaces the column name with a generated default name. The default name consists of the letter C followed by a three digit sequence number. This number corresponds to the count of nameless columns in the SQL output (leading zeros are used, to assure three digits). For example, if the SQL query is SELECT A,B,A+B ..., then the A+B column will be assigned the name C001, since it is the first nameless column.

57.9 Matching Algorithm Summary

Search Order
The following steps are taken to couple resultant SQL columns with eMerge fields. They reflect the order in which a match is made, i.e. once the conditions for a match are fulfilled, later steps are not taken. 1 Explicit Coupling - Attempt to couple explicitly matched columns. 2 Table Designators - Attempt to couple columns with table designators. 3 Unique eMerge Field - Attempt to couple remaining named columns to a unique field in the object table(s).

57-7

57

Advanced SQL Queries Referencing SQL Columns in the eMerge Method

4 Virtual eMerge Field - Couple unmatched named columns to generated virtual fields. 5 Virtual eMerge Cnnn Field - Couple nameless columns to generated virtual fields (default name of Cnnn).

Search Scope
Type of Field User Parameter Implicit Couple Explicit Couple Qualified Explicit Couple Table Designator Example @field SELECT field AS field AS class.field table.column Search Scope knowledgebase SELECT tables knowledgebase class table

Class and table are essentially equivalent; table refers to an SQL table, and class refers to an eMerge class. It is possible to have an existing SQL table without a corresponding eMerge class.

57.10 Referencing SQL Columns in the eMerge Method

The following is a summary of how to reference SQL columns from query statements outside the SQL query. The PRINT statement represents a reference to an SQL column from beyond the scope of the SQL query. Example:
FOR ALL MYQUERY1. ... DEFINE SQL QUERY MYQUERY1 SELECT COL1, T1.COL2, T2.COL2 AS CLS30.F1, COL4 AS MY_FLD FROM DEMO.TABLE1 T1, DEMO.TABLE2 T2; ...

Correct References
The following syntactically correct PRINT statement examples refer to MYQUERY1. PRINT COL1 PRINT F1
57-8

correct

correct

Advanced SQL Queries Referencing SQL Columns in the eMerge Method

PRINT MY_FLD

correct

Incorrect References
The following incorrect PRINT statement examples refer to MYQUERY1. PRINT MYQUERY1.COL1 PRINT T1.COL2 invalid format outside of query

cannot reference table designator cannot reference table designator cannot reference SQL table

PRINT COL2 OF T1

PRINT COL2 OF DEMO.TABLE2

PRINT F1 OF CLS30 Though a field in an AS clause (the AS object) can be qualified syntactically, it is logically incorrect to qualify such a field clause when referring to it outside the SQL query. This is because the object of the AS clause names a coupling field, which results in the creation of a virtual field of that name. The virtual field is referenced without qualification. A qualified reference results in the real field being referenced. PRINT COL1 OF MYQUERY1 PRINT F1 OF MYQUERY1 field cannot be qualified by query

object of AS cannot be qualified by query object of AS cannot be qualified

PRINT F1 OF CLS30 OF MYQUERY1 by query PRINT CLS30.F1 PRINT COL4

invalid format outside of query

renamed by AS object of AS cannot be qualified by

PRINT MY_FLD OF MYQUERY1 query

Coupling Examples
The following shows the coupling process for the preceding SQL query. Note that coupling takes place during query compilation, and not during execution. For convenience, the query is shown here again:

57-9

57

Advanced SQL Queries Referencing SQL Columns in the eMerge Method

FOR ALL MYQUERY1. ... DEFINE SQL QUERY MYQUERY1 SELECT COL1, T1.COL2, T2.COL2 AS CLS30.F1, COL4 AS MY_FLD FROM DEMO.TABLE1 T1, DEMO.TABLE2 T2; ...

COL1 The eMerge concepts corresponding to DEMO.TABLE1 and DEMO.TABLE2 are searched. If COL1 is found and it is unique, it is coupled. If it is not found, a virtual field called COL1 is generated. If it is not unique, a query compile error results. T1.COL2 The eMerge concept corresponding to DEMO.TABLE1 is searched. If COL2 is found and it is unique, it is coupled. Although an eMerge concept cannot contain duplicate fields, a field may have a synonym identical to another field name, thereby causing it to be non-unique. If it is not unique, compilation is terminated and an error message is issued. If it is not found, a virtual field called COL2 is generated and coupled. T2.COL2 The eMerge CLS30 is searched for field F1. If field F1 is found and it is unique, it is coupled. Although an eMerge concept cannot contain duplicate fields, a field may have a synonym identical to another field name, thereby causing it to be non-unique. If it is not unique, compilation is terminated and an error message is issued. If it is not found, a virtual field called F1 is generated and coupled. Note that if this column were not explicitly coupled, an error would occur, because it would be a duplicate column name (T1.COL2 and T2.COL2). COL4 If a virtual field called MY FLD has been explicitly defined, it is coupled. If a real field named MY_FLD is found and it is unique, it is coupled. It does not necessarily have to be defined in a segment. Otherwise a virtual field called MY_FLD is generated.

Coupling Summary
Knowing which field is a candidate for coupling, enables the developer to control and fine tune the results of a query. The following table summarizes the coupling dependencies necessary for a successful
57-10

Advanced SQL Queries Referencing Compound Names in the eMerge Method

compilation of the above SQL query. The names of the SQL tables and columns in the above example are used for simplicity; they imply the corresponding eMerge data item intended for coupling. Reference
PRINT COL1 PRINT COL2 PRINT F1

Knowledgebase Dependency COL1 must be unique across DEMO.TABLE1 and DEMO.TABLE2, or must not exist there. COL2 must be unique across DEMO.TABLE1, or must not exist there. F1 must exist in SEG30 (and be unique there). knowledgebase, or not exist at all.

PRINT MY_FLD MY_FLD must exist uniquely across the

57.11 Referencing Compound Names in the eMerge Method

eMerge allows field names to include blanks, e.g. EMP NAME.

57.12 Working with Zoned Data Type in i5/OS

Special treatment may be necessary for an SQL table with a column of type CHAR mapped to a field in eMerge of type ZONED, as follows: SQL Column Name SQL_CHAR Type Char[5] eMerge Field Name EMERGE_ZONED Type Zoned[5]

SQL produces SQL CODE -301 at run time if an SQL query has the following SQL statement:
"select * from "SQL-TABLE" where SQL_CHAR = @EMERGE_ZONED;"

Two suggested solutions are presented here.

Using a Declare Statement

To solve the problem, change the SQL statement:
"select * from "SQL-TABLE" where SQL_CHAR = @EMERGE_CHAR;"

Add this line to the query:

57-11

57

Advanced SQL Queries Replacing Strings in an SQL View Statement

"declare EMERGE_CHAR char 5 as EMERGE_ZONED;"

Using an SQL Function

You can write an SQL function to perform the conversion.

57.13 Replacing Strings in an SQL View Statement

Strings appearing in an SQL View statement can be replaced dynamically at runtime. A String Replacement table is built that contains the mapping between source strings and their replacement target strings. In the SQL View statement itself the source string to be replaced is enclosed within a replacement deliminator ([ ])

The replacement deliminator can not be a single or double quotation mark).

At runtime, the SQL View statement is parsed, and for any strings within a replacement deliminator, a look-up is performed in the String Replacement table. If the source string is found in the table, it is replaced by its replacement target string. If the source string is not found in the table, an error message is issued. To specify a replacement string: 1 Access the SQL DBMS Definition (23407) form:

57-12

Advanced SQL Queries Replacing Strings in an SQL View Statement

2 Click ReplaceString. The SQL Replace String (23434) form is displayed:

57-13

57

Advanced SQL Queries Replacing Strings in an SQL View Statement

3 In the Source String textbox enter the name of the string to be replaced. The source string can be any string containing alfanumeric as well as special characters (e.g. blank, minus, slash, back slash, dot , underline, etc). It is non-case sensitive string up to 32 characters in length. The following strings are reserved and cannot be used for a source string: TAB CRT, TAB-CRT, TAB_CRT, CRT TAB, CRT-TAB, CRT_CRT,CREATOR TABLE, CREATOR-TABLE, CREATOR_TABLE, TABLE CREATOR, TABLE_CREATOR, TAB LOC, TAB-LOC, TAB_LOC,LOC TAB LOC-TAB, LOC_TAB,LOCATION TABLE, LOCATION_TABLE, LOCATION_TABLE,TABLE LOCATION< TABLE_LOCATION 4 In the Target String textbox enter the name of the replacement string. 5 Select a replace rule from the Replace Rule drop-down listbox. The replace rule determines how replacement is performed.

57-14

Advanced SQL Queries Handling SQL Multi-Platform Syntax Issues

AsIsThe target string replaces the source string as is without any additions. Table CreatorThe source string is replaced as follows: For SQL DBMS type ORACLE and DB2, a dot (.) character is added after the target string. For SQL DBMS type i5/OS/DB2, a dot (.) character (or slash (/) character if SYS-SQL is option is assigned in the Adapter Profile) is added after the target string. Table LocationThe source string is replaced as follows: For SQL DBMS type DB2 (not i5/OS), a dot (.) character is added after the target string. For SQL DBMS type ORACLE, an at (@) character is added after the target string. Part of ConstantThe source string is replaced as follows: If the character before or after the source string is a single or double quotation mark, then the target string replaces the source string with the quotation marks adjacent to the target string removed. Example: Source string is: "abc" [t1] "def". Replacement target string is: kk. The resulting string after replacement is: "abc kk def".

The following applies: If the value TABLE-CREATOR is used for the source string, then Table Creator must be selected for Replace Rule. If the value TABLE-LOCATION is used for the source string, then Table Location must be selected for Replace Rule. 6 Assign any options that are required to control the replacement behaviour. 7 Click OK

57.14 Handling SQL Multi-Platform Syntax Issues

In a multi-platform environment, when developing SQL based applications, issues arise from differences in the SQL syntax between the platforms. In such cases, use directives in fetchSQL statements and in SQL query statements to avoid compilation problems with SQL formulas. A directive (i.e. a string starting with a percent sign (%)) instructs the system to compile the appropriate SQL statement that is specific to the particular running environment (see "Directives" below).

57-15

57

Advanced SQL Queries Handling SQL Multi-Platform Syntax Issues

When the eMerge Syntax option is assigned via the DBMS definition form, an OPTIONS SYNTAX=SQL clause must be implicitly used in a fetchSQL rule and in an SQL query.

The following examples illustrate some of these issues: Example:

TRANSLATE

The DB2 DIGITS function is not supported in Oracle. The function gives a similar result to the DB2 DIGITS function.

... %DB2 DIGITS(T4.COV_PROP_SEQ) %ORA TRANSLATE(TO_CHAR(T4.COV_PROP_SEQ,00000), %ORA 012345789-+.,,0123456789)

It is the users responsibility to determine the number of digits before and after the decimal point.

Example: DB2 arithmetic operations with date and time type are different in Oracle:

INTERVAL data type is used to specify a number of days/months/years.

... %DB2 AND (LOSS_DATE + 4 YEARS) <= :EFFECTIVE-DATE %ORA AND (LOSS_DATE + INTERVAL 4 YEAR) <= :EFFECTIVE-DATE ; ...

NUMTOYMINTERVAL(<Number-of-Years>,YEAR) is used to convert months/years to date format.

... %DB2 %DB2 %ORA %ORA ... %DB2 %DB2 %ORA %ORA ; ...

date(cast(:tmp-c-10 as char(10))) + pol_term_cd years cast(cast(:tmp-c-10 as char(10)) as date) + NUMTOYMINTERVAL(POL_TERM_CD,YEAR) else else date(cast(:tmp-c-10 as char(10))) + pol_term_cd month cast(cast(:tmp-c-10 as char(10)) as date) + NUMTOYMINTERVAL(POL_TERM_CD,MONTH)

Example: The Fetch first row feature is not supported by Oracle. To get the first row in Oracle, the original SELECT statement must be included within the following SELECT statement:
SELECT * from (<original select statement>) where ROWNUM=1

57-16

Advanced SQL Queries Handling SQL Multi-Platform Syntax Issues

... SELECT %ORA * FROM (SELECT CHG_POL_PREM_AMT, CANC_REINST_FTR FROM POLICY_ENDRSMNT WHERE POL_SYMBOL = :F7700 ... ORDER BY PROCESS_DATE DESC, PROCESS_TIME DESC %ORA ) WHERE ROWNUM = 1 %DB2 fetch first row only ;

Directives
The following is a list of supported directives: Directive %ORA %ORACLE %ORA-UNIX %ORACLE-UNIX %ORA-LINUX %ORACLE-LINUX %ORA-HPUX %ORACLE-HPUX %DB2-ISERIES %DB2-Z/OS %DB2-VM The following applies when using directives: A directive must start at the very beginning of a rule or query statement line. A rule or query statement that contains a directive cannot have a semicolon (;) that is used as an end-of-statement as part of the statement line. %ORA and %ORACLE are synonyms. %ORA is a directive that can be used in place of the Oracle directives %ORA-HPUX and %ORA-LINUX and %ORA-UNIX.

57-17

57

Advanced SQL Queries Handling SQL Multi-Platform Syntax Issues

%DB2 is a directive that can be used in place of the DB2 directives %DB2-ISERIES and %DB2-VM and %DB2-Z/OS. When there is a difference between the platforms, then a platform specific directive must be used.

57-18

Chapter 58 Common Query Errors

There are several different kinds of query errors:

Syntax errors Logic errors Format errors

Some of these errors are identified at compilation time, and others only at run time. Following are examples of query errors and their solutions.

58.1 Syntax Errors

Syntax errors are detected at compilation time.

Typographic or Spelling Errors

Typing a class name incorrectly, for example results in this error message:
for all employyee. print by employee-name salary hire-date.

The error message states that the class name Employyee is not defined. Typing a field name incorrectly, for example results in this error message:
58-1

58

Common Query Errors Syntax Errors

for all employee. print by employyee-name salary hire-date.

The error message states that the field name Employyee-Name is not defined.

Hyphen Missing in Compound Field Name

Not replacing blanks and special characters in a name, results in this error message: Example:
for all employee. print by employee name salary hire-date.

Since the hyphen is missing in the Employee-Name field, an attempt is made to produce a printout for two separate field names, Employee and Name.

Period Missing at End of Statement

Not ending a statement with a period, results in this error message: Example:

58-2

Common Query Errors Logic Errors

for all employee. print by employee-name salary hire-date break space by employee-name salary.

A continuation of the PRINT statement is expected. A different message results if the period is missing from the last statement of the query, results in this error message: Example:
for all employee. print by employee-name salary hire-date

A continuation of the PRINT statement is expected. Check each statement for all periods, hyphens, parentheses, etc.

58.2 Logic Errors

Some examples of logical errors include:

duplicate query sorting requests non-specific reference to data objects (field, class, composite) referencing data objects that are not in the same context

58-3

58

Common Query Errors Logic Errors

Duplicate sorting
Sorting the data via different statements, results in this error message: Example:
for all employee. print by employee-name salary hire-date. break space by employee-name salary.

Both the PRINT statement and the BREAK statement include the BY keyword, to sort on the same fields.

Class Name and Field Name Not in Same Context

Requesting information from diverse, unrelated classes, results in this error message: Example:
for all positions. print by employee-name salary hire-date. break space by employee-name salary.

Any relationships that exist between classes (via the fields in the classes) is handled. However, if you have requested data from subject areas between which there is no relationship, an error is returned.

58-4

Common Query Errors Format Errors

Multiple Match for Names

Including a field name which is used in more than one class, results in this error message: Example:
for all employee. print by employee-name salary start-date.

There are two classes that contain a field Start Date (classes 55 and 60). eMerge does not know which class you intended to refer to in this query. Qualify the correct field, by including the composite name in the query, for example:
for all employee. print by employee-name salary start-date of project-employee.

58.3 Format Errors

Several kinds of format errors can occur, such as:

Output line too long. Too many read operations. Full sort buffers. Too many output lines.

Output Line Too Long

When the report line is longer than the maximum output line (79 on a standard terminal), the following message is produced:

58-5

58

Common Query Errors Format Errors

No output is produced in this case. To prevent this error do one of the following:

Enter the SCROLLINE command in Command Handler, with a value less than 254, but greater than the output line size. Use the OVER option (see "Printing More than One Field in a Column" on page 51-9). Change the title of a field where the length of the value is significantly less than the length of the title. To change the title in a specific query see "Renaming a Field Using a Virtual Field" on page 52-10. To change the title globally, for all queries, see "Renaming a Field for a Query" on page 51-21. Remove some fields from the PRINT statement.

If the query is only run in batch, the LINESIZE parameter in the OPTIONS statement can also be used.

Too Many Read Operations

When your query reads more database composites than the maximum allowed, an error results. You receive the output for the composites which were processed.

Full Sort Buffers

When your query includes sorting, and the amount of main storage assigned to the sort program is insufficient, an error results. No output is produced in this case. To prevent this error, you must consult your Administrator who can either enlarge the buffers or (if available) provide you with the SORT SYS option for this query.

58-6

Common Query Errors Error Messages When Running in Batch

Too Many Output Lines

By default you receive the maximum number of lines allowed for an output area. When your report includes more lines than the output area allows, an error results. To avoid this error, run the query in batch.

58.4 Error Messages When Running in Batch

Refer to eMerge Applications via 3270-Display for details about running eMerge in batch. When you run a query in batch with an error in the query, the error message appears in the batch output. For example, running the query example shown on page 58-1 (employee is incorrectly spelled in the FOR statement), results in the following batch report:
MSG7000 ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** eMerge (TM) session started on 29.03.2005 ; ** Software version = 44 release = 11 ; ** Pure version = 44 release = 11 ; ** (C) Copyright 2005 ** Sapiens International Corporation N.V. ** All rights reserved. ** This program is protected by the Copyright Law ** as an unpublished work. ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** MSG2675 RUN NO. 32 , SYSTEM-ID IS ESTEST QUERY 930000 ERR6601 The view "EMPLOYYEE" used in the first statement must 1MSG2676 RUN NO. 32 UNDER SYSTEM-ID ESTEST HAS FINISHED. MSG3003 -------------- BLP STATISTICS -------------- FOR TASK --- OPERATIONS: INPUT : GOOD : --- SUBJECT OPERATIONS (CHECKS AND DECODE): IN MEMORY : . . ** ** ** ** ** ** ** ** ** ** ** ** ** ** be defined. ID : ESTEST

58-7

58

Common Query Errors Error Messages When Running in Batch

. NUCLEUS REFRESH STATISTICS: NUMBER OF COMPOSITES REFRESHED IN LAST REFRESH OPERATION WAS 0 AVERAGE NUCLEUS REFRESH COUNT IS 0 COMPOSITES.

After the log on information the report shows the command entered, QUERY 930000, and under it the error message. The normal BLP statistics follow the error message to complete the report.

58-8

Part H

External Programs

Chapter 59 Calling External Programs from eMerge

59.1 Using External Programs

Use external programs in the following circumstances:

Update the data without generating an operation Time-dependent processing (i.e. end of year processing) Functions that utilize external code modules (i.e. common date or tax routines) Complex reporting outside the scope of the eMerge query language

59.2 Calling from Messages or Rules

External programs can be called via messages or via rules.

For information on programs as messages, see Chapter 32, Accessing the Data. For information on calling programs from rules, see Chapter 20, Using a Call Rule.

59.3 Supported Programming Languages

The following programming languages are supported on Business Integrity Server platforms: Language DBCOBOL DBPL1 IBM Assembler C 4 4 4 4 4 z/OS and z/VM 4 i5/OS HP-UX and Linux

59-1

59

Calling External Programs from eMerge Supported Programming Languages

For information on DBCOBOL see the DBCOBOL Guide for details. For information on DBPL1 see the DBPL1 Guide for details. For information on C see Chapter 60, Calling C Programs from eMerge Under i5/OS, HP-UX and Linux.

59-2

Chapter 60 Calling C Programs from eMerge Under i5/OS, HP-UX and Linux

Under i5/OS, HP-UX, and Linux you can call a C program from eMerge.

60.1 Creating a Program to be Run from eMerge

The steps summarized here are described in this chapter.

Prepare the C Program

Create the C program. Compile it and link it. Define it in eMerge.

Define the Composite, Classes, Fields and Operations

Define the composite, classes and fields. Define the operation that is to be displayed to the user for data input and display. Modify the forms that are generated for the operation, if necessary.

Create Rulesets
A program that has outputs must be run via a ruleset. A program invoked via the PERFORM command cannot return parameters. Create a ruleset (without rules) to invoke the program. Create another ruleset containing a call rule (to call the ruleset that invokes the program) and a computation rule (to store and echo the result).

60-1

60

Calling C Programs from eMerge Under i5/OS, HP-UX and Linux Create the C Program

Information Flow

Ruleset Call Rule Computation Rule Ruleset Program Definition in eMerge trigger

Composite Class Output Field Input Field Form Operation

C program

60.2 Create the C Program

Create the C program as described here. The sapfwkdy program, shown in the examples, accepts a date and returns the day of the week on which that date falls.

BLP_Program Statement
The C program must contain this statement:
BLP_Program (<program name>).

Function Name
The name of the function defined via the BLP_Program statement in your program must be identical to the Program ID defined in the Program Definition form. It must be in uppercase and no longer than eight characters. HP-UX Linux i5/OS Under HP-UX and Linux, this is the shared library name. Add the compiled program to the PATH and to the SHLIB_PATH. Under i5/OS this is the service program name. Add the compiled program to *LIBL.

60-2

Calling C Programs from eMerge Under i5/OS, HP-UX and Linux Compile and Link the C Program

Header Files
Include the header file emerge.h that contains the parameters and structure needed by C programs running from the BLP. Separate header files, such as saptwkdy.h in the example below, should include the private program parameter structures.

Supply Compiler Options in HP-UX and Linux Header Files

HP-UX Linux In order for data to be passed correctly from eMerge to the user program written in C, you must add the following lines before and after the eMerge data structure definition in the header files created by the user:
#pragma HP-ALIGN NOPADDING PUSH #pragma HP-ALIGN POP

Before Data Structure After Data Structure

Example
These lines from a C program contain the standard emerge.h header file. The BLP_Program statement is shown.
#include <stdio.h> #include <stdlib.h> #include #include #include #include "sapfwkdy.h" "emerge.h" "emdates.h" "empacked.h"

BLP_Program(SAPFWKDY) { ... program definition ... }

60.3 Compile and Link the C Program

Use these templates to compile and link the C program.

60-3

60

Calling C Programs from eMerge Under i5/OS, HP-UX and Linux Compile and Link the C Program

Under i5/OS
The EXAMPLEC file contains a compilation example in the COMPILE member. The compilation creates a service program whose name must be defined in the BLP_Program statement.
Assuming that the user had copied the C sources to file C in library USER_CPROGS, and the header files are in the same library, the C module would be created by typing the following: ** CRTCMOD MODULE(USER_CPROGS/SAPFWKDY) SRCFILE(USER_CPROGS/C) And the service program would be created as follows: ** CRTSRVPGM SRVPGM(USER_CPROGS/SAPFWKDY) MODULE(USER_CPROGS/SAPFWKDY) BNDSRVPGM(SAP4024/SAPCONVERT) ALWRINZ(*YES) EXPORT (*ALL)

EXPORT(*ALL) This enables export to the name defined in the BLP_Program statement. ALWRINZ(*YES) Alignment must be specified.

Under HP-UX
There is a sample compilation in the file readme.compile in the /example directory. Compilation Flags +DD64 +u1 +Z work with 64 bit

alignment shared library exports the function name used in the

+e <BLP_Program name> BLP_Program statement Linkage Flags

-l the library to be used. libsapconvert.sl contains functions used by the example. -L Where to find the shared library. OPSAPDIR is the eMerge software library. +s, -b these options must be used

60-4

Calling C Programs from eMerge Under i5/OS, HP-UX and Linux Define the Program in the eMerge Program Definition Form

Compilation Example

The compilation produces a shared library. Its name must be the name of the BLP program (without the .sl file type).

# # This is a compilation example for the sapfwkdy.c BLP_Program. # The following line compiles the example program and creates # the object sapfwkdy.o, and exports the BLP_Program name # (using the -e option) # cc -c -Ae -g +DD64 +u1 +Z -e SAPFWKDY sapfwkdy.c # # The object must be linked to create a shared library # from the BLP_Program: # ld -lc -L ${OPSAPDIR}/bin -l sapconvert +s -b sapfwkdy.o -o SAPFWKDY

60.4 Define the Program in the eMerge Program Definition Form

In the Program Definition form, the Language of the C program should be defined as Cobol. The Program ID is the name of the compiled C program. In the Invoked by Ruleset field, place the number of the ruleset defined to invoke the program. See "Define a Ruleset to Invoke the C Program" on page 60-10.

60-5

60

Calling C Programs from eMerge Under i5/OS, HP-UX and Linux Define the Fields, Operation and Forms

List the fields you have defined for input data and output data.

60.5 Define the Fields, Operation and Forms

The forms shown ere illustrate the definitions of fields to serve as input and output parameters for the program. They show how to define the composite, class and operation, and show a sample generated form.

60-6

Calling C Programs from eMerge Under i5/OS, HP-UX and Linux Define the Fields, Operation and Forms

Defining a Date Input Field

Defining a Binary Output Field

60-7

60

Calling C Programs from eMerge Under i5/OS, HP-UX and Linux Define the Fields, Operation and Forms

Defining a Composite

Defining a Class

60-8

Calling C Programs from eMerge Under i5/OS, HP-UX and Linux Define the Fields, Operation and Forms

Defining an Operation

Define an operation containing the fields.

Customize Generated Forms

Modify the forms generated for the operation, as necessary.

60-9

60

Calling C Programs from eMerge Under i5/OS, HP-UX and Linux Define a Ruleset to Invoke the C Program

60.6 Define a Ruleset to Invoke the C Program

In the Invoked Program No. field, place the number of the definition of the C program.

60.7 Define a Ruleset to Pass Program Parameters

A program that has outputs must be run via a ruleset. A program invoked via the PERFORM command cannot return parameters. Define the following rulesets for the example:

Defining a Ruleset
In the case of the example, define a ruleset to be triggered on insert.

The ruleset for the example contains a call rule and a computation rule:

60-10

Calling C Programs from eMerge Under i5/OS, HP-UX and Linux Define a Ruleset to Pass Program Parameters

Defining a Call Rule to pass Parameters to the Ruleset that Invokes the C Program
This call rule calls the Find Week Day ruleset which invokes the C program. It specifies the Date field as the input to the program, and Return Weekday as a place to hold the output.

60-11

60

Calling C Programs from eMerge Under i5/OS, HP-UX and Linux eMerge.h Header File

Define a Computation Rule to Write the Results

Define a computation rule to write the results to the Weekday 27000 field.

60.8 eMerge.h Header File

The supplied header file, emerge.h, defines the parameters received by a C program running under eMerge, and the BLPStatus structure. It should be included in every C program to be run under eMerge.

60.9 Templates for Private Header Files

Each C program must have the standard header file, emerge.h, supplied with and required by eMerge. A separate header file should contain definitions needed by the user program. Each program has its own definition for this structure. The structure must be defined. If no fields are passed to the program, use a dummy field in the structure. The order of the fields is the same as the order of the fields in the Program Definition form, for all the fields defined with the MOVE option. The eMerge header file points to structures for the private parameters used by the program. Use this template to build a header file to describe input and output parameters for the C program.

60-12

Calling C Programs from eMerge Under i5/OS, HP-UX and Linux Data Types

*/ */ */ */ */

/* these structure should be defined in a separated .h file /* for each program according to the defined parameters. /* in case there are no parameters use: /* void *<name>; /* as default. /* struct ProgParms { short int ProgParmsLength; struct PrivateParm PrivateProgramParm; }; struct RetValues { short int RetValuesLength; struct PrivateReturn PrivateReturnedValues; }; struct PrivateParm { .. place fields here ... }; struct PrivateReturn { ... place fields here ... };

60.10 Data Types

Not all C data type are supported in eMerge. The table below shows how to convert an eMerge data type into a C data type. The length refers to the Field Length value in the field definition. The returned fields must be updated. eMerge type binary, length = 2 C type C definition <name>;

unsigned short int <name>;

binary, length = 2 short int with MayBeNegative or MinusOne binary, length = 4 binary, length = 4 long int with MayBeNegative or MinusOne

unsigned long int <name>; <name>;

60-13

60

Calling C Programs from eMerge Under i5/OS, HP-UX and Linux Example Files

eMerge type character dual graphic hexadecimal packed decimal date zoned decimal char char

C type

C definition <name>[length]; <name>[length]; <name>[length]; <name>[length]; <name>[length]; <name>[length]; <name>[length];

unsigned char unsigned char unsigned char unsigned char char

60.11 Example Files

These files are used with the program shown in the examples: HP-UX Linux i5/OS The sample files reside in <spath>/examples where <spath> is the eMerge software path. The sample C source and header files are provided as members in the SAMPLEC and SAMPLEH files, respectively.

sapfwkdy.c
A sample C program to calculate the day of the week for a date.

sapfwkdy.h
This header file defines the input and output parameters for the program. They correspond to the eMerge fields.
#ifndef SAPFWKDY_H #define SAPFWKDY_H struct PrivateParm { unsigned char short int }; struct ProgParms { short int
60-14

InputDate[4] ; WeekDay ;

ProgParmsLength;

Calling C Programs from eMerge Under i5/OS, HP-UX and Linux Example Files

struct PrivateParm }; struct PrivateReturn { void }; #endif

PrivateProgramParm;

*kuku;

empacked.h
Functions defined in this file perform the conversion of a packed decimal field into an integer or real number. 4. HP-UX Linux The functions are defined in the libsapconvert.sl library. i5/OS The functions are defined in the SAPCONVERT library.

emdates.h
These functions perform the following conversions:

an eMerge date field into a C structure of dd, mm and yy a dd mm and yy C structure into an eMerge date field

HP-UX Linux i5/OS

The functions are defined in the libsapconvert.sl library. The functions are defined in the SAPCONVERT library.

60-15

60

Calling C Programs from eMerge Under i5/OS, HP-UX and Linux Example Files

60-16

Chapter 61 Using SAPUTMON to Access Business Integrity Server via External Programs

The SAPUTMON module allows a program to work interactively with Business Integrity Server. The module monitors calls from the program, and returns Business Integrity Server responses to the program.

61.1 Stages of a Business Integrity Server Session

The program issues an INIT call to start Business Integrity Server. The user ID and password are sent, and the interactive session is conducted and ended, by issuing TRAN calls.

INIT Call
The first call passes to SAPUTMON the following parameters: the INIT identification, BLP parameters to be used for starting the session, the address and length of the buffer you supply to receive Business Integrity Server responses. eMerge returns the return code, reason code, and messages in the buffer.

TRAN Call to Send the User ID and Password

The next call passes the TRAN identification, user-ID and password, buffer address, and buffer size. eMerge returns the return code, reason code, and messages in the buffer.

Changing the Input/Output Type for a Message

Before a TRAN call to send a BLP command, a call is made to set the input/output type for the next message. Use a SET call to set the input/output type (e.g. XML) for subsequent messages. Once the input/output type is set, several TRAN calls can follow.

61-1

61

Using SAPUTMON to Access Business Integrity Server via External Programs Parameters for Business Integrity Server Initialization

TRAN Calls to Send BLP Commands and Operations

Subsequent calls pass the TRAN identification, a BLP command or operation, buffer address, and buffer size. eMerge returns the return code and reason code. The results of the BLP command or operation are returned in the buffer. The last call passes the END command, buffer address, buffer size. eMerge returns the return code, reason code, and messages in the buffer.

61.2 Parameters for Business Integrity Server Initialization

To initialize Business Integrity Server, pass the following parameters to SAPUTMON:

INIT Identification
The INIT identification is as follows: INIT

BLP Parameters
A list of the BLP parameters separated by commas: <length> two bytes <BLP-parameters> length

<length> The length of the BLP parameter string. The value does not include the two bytes of its own length. <BLP parameters> The order is as follows:

<general-parms>,<mem-size>,<nucleus-size>, <separator>,<date>,<dbid>,<prefix> The BLP parameters are described in Business Integrity Server Utility Reference.

61-2

Using SAPUTMON to Access Business Integrity Server via External Programs Parameters for Business Integrity Server Initialization

SET Call Parameters

Sets the input/output type. This call passes the SET ID. The format is as follows: <length> two bytes <msg>
Input=XML, output=XML

length-2

To return to the default settings, invoke another SET call as follows: <length> two bytes <msg>
Input=TRANS, output=list

length-2

<length> The length of the SET call. The value includes the two bytes of its own length. <msg> The input and output type.

TRAN Calls to Send XML Input

TRAN calls after a SET call to XML should have the following input format: <length> four bytes <XML (input buffer)> length-4

<length> The length of the TRAN call. The value includes the four bytes of its own length. <XML(input buffer)> The XML message.

Output Buffer for XML

When working with XML, the output returned by BIS does not use the output buffer allocated by the user program, rather an output buffer supplied by BIS. The output has the following format:

61-3

61

Using SAPUTMON to Access Business Integrity Server via External Programs Parameters for Business Integrity Server Initialization

<length> four bytes

<XML data> length-4

The output buffer size should ,nevertheless, be supplied to retain compatibilityeven though it is not used when working with XML.

Buffer Address
SAPUTMON returns the output results from Business Integrity Server to this address. The buffer has the following structure: 0 1 2 3 4 number of lines (two bytes) the buffer (Business Integrity Server returns the results here) line length (two bytes)

The default for the line length is 133 (defined by the LINESIZE command).

Buffer Size
Supplied by the user (four bytes): buffer size = (number of lines) X (line length)

Return Code
Indicates how Business Integrity Server completed the operation (two bytes).

Reason Code
Explains the return code (four bytes).

61-4

Using SAPUTMON to Access Business Integrity Server via External Programs Parameters for Session Logon

Return Code 0 4 8 12

Reason Code warning or message code error code 0 4 8 16

Explanation Operation completed correctly. Operation completed with a warning code. Operation completed with an error code. Business Integrity Server completed this session. Business Integrity Server completed with warning code. Business Integrity Server completed with an error code. An abend occurred in Business Integrity Server. A system abend occurred in Business Integrity Server. A recursive abend occurred. Displayed abend code occurred before the current abend code. Invalid input for INIT call. Invalid input for TRAN or END call. Invalid parameters. eMerge session already in use.

16 20 24 28 32 36

abend code abend code

61.3 Parameters for Session Logon

After initializing Business Integrity Server, send the user ID and password:

TRAN Identification
The operation identification is as follows: TRAN

61-5

61

Using SAPUTMON to Access Business Integrity Server via External Programs Parameters for a Session

User ID and Password

The user ID and password, separated by a comma, are sent as follows: <length> two bytes <user-ID password> length

<length> The length of the user identification and password. The value includes the two bytes of its own length.

Buffer Address, Buffer Size, Return Code, Reason Code

As described in "Parameters for Business Integrity Server Initialization".

61.4 Parameters for a Session

After initializing Business Integrity Server, and sending the user ID and password, send data or requests to Business Integrity Server:

TRAN Identification
Pass the operation identification as follows: TRAN

Input Operation or BLP Command

Input operations or BLP commands are sent as follows: <length> two bytes <operation or command> length

<length> The total length of the operation or command. The value includes the two bytes of its own length.

Buffer Address, Buffer Size, Return Code, Reason Code

As described in "Parameters for Business Integrity Server Initialization" on page 61-2.

61-6

Using SAPUTMON to Access Business Integrity Server via External Programs Linking to SAPUTMON

61.5 Linking to SAPUTMON

You can link a program to SAPUTMON dynamically or statically. All the COBOL programs that you use with SAPUTMON must use the same type of linkage option (either dynamic or static).

Under TSO for z/os

The SAPUTMON module is linked with the REUS option and resides in the Business Integrity Server LINKLIB library. The SAPUTMON object resides in the Business Integrity Server LOADLIB library. Dynamic Link If you want to use the dynamic option, the SAPUTMON module is used in this case. It is loaded from the LINKLIB library. This allows you to call SAPUTMON dynamically from any COBOL program. It also allows you to run in parallel several programs with the same SAPUTMON copy. If you want to use the static option, the SAPUTMON object is used. It is linked from the Business Integrity Server LOADLIB library to your program. You can then run only one program, because the linked COBOL program includes SAPUTMON.

Static Link

Under z/VM
Dynamic Link If you want to use the dynamic option you do not need to perform any links (only one copy of SAPUTMON TEXT resides in memory). This allows you to call SAPUTMON dynamically from any COBOL program. It also allows you to run several programs in parallel with the same SAPUTMON copy. If you want to use the static option you have to create a CMS LOADLIB library and SAPUTMON has to be link-edited with a COBOL program. You can then run only one program, because the link-edited COBOL program includes SAPUTMON.

Static Link

61-7

61

Using SAPUTMON to Access Business Integrity Server via External Programs Linking to SAPUTMON

Under i5/OS
Use the following utilities with the SAPUTMON module:

UTMON Creation (CRTUTMON)To compile, link and bind a COBOL, RPG, or C program that uses SAPUTMON to access Business Integrity Server. UTMON Run (RUNUTMON)To run a COBOL, RPG, or C program that uses SAPUTMON to access Business Integrity Server. DBCOBOL Compilation (CRTDBCBL)To compile a DBCOBOL program. DBCOBOL Run (RUNDBCBL)To run DBCOBOL programs.

Or, use the following:

Under HP-UX and Linux

Use the following utilities with the SAPUTMON module:

UTMON Creation (crtutmon)To compile, link and bind a COBOL, RPG, or C program that uses SAPUTMON to access Business Integrity Server. UTMON Run (runutmon)To run a COBOL, RPG, or C program that uses SAPUTMON to access Business Integrity Server. DBCOBOL Compilation (dbcob)To preprocess, compile, link and perform the GO of a DBCOBOL program. This runs the DBCOBOL Precompile (dbcobp) utility and the DBCOBOL Run (dbcobg) utility. DBCOBOL Run (dbcobg)To run the executable COBOL module obtained from running the DBCOBOL Compilation (dbcob) utility (default) or to run the report module obtained from running the DBCOBOL Precompile (dbcobp) utility using the output of the GO step.

Or, use the following:

Restrictions
After your user program has issued the INIT MONITOR call you cannot call a COBOL program, as the Business Integrity Server is already accessed by the monitor. For the same reason, your DBCOBOL user program cannot call the monitor from within its session.

61-8

Using SAPUTMON to Access Business Integrity Server via External Programs Sample Programs

You can call a COBOL program only when the END MONITOR command was issued by your user program.

61.6 Sample Programs

Sample Program to Call SAPUTMON
In this example, the program calls SAPUTMON to start Business Integrity Server, to send the user ID and password, and to send an operation and print the resulting contents of the buffer. A listing of the PRINTBUF program is given in "Sample Program to Print the SAPUTMON Buffer" on page 61-11.
IDENTIFICATION DIVISION. PROGRAM-ID. EXAMPLE. ENVIRONMENT DATA ** Test OPERATION-CODE 'TRAN' ** Send TRANSACTION 100,A till overflow of buffer WORKING-STORAGE 01 I 01 OPERATION-CODE 01 BUFFER. 10 10 10 10 NUM-LINES LEN-LINES FILLER LINE-ARRAY PIC 9(2) PIC 9(2) USAGE IS BINARY. USAGE IS BINARY. PIC PIC 9(2) X(4). SECTION. USAGE IS BINARY. DIVISION. DIVISION. ** **

******************************************************

******************************************************

PIC X(129). PIC X(133) OCCURS 1 TO 1000 TIMES DEPENDING ON NUM-LINES. PIC 9(8) PIC 9(2) PIC 9(8) PIC 9(2) USAGE IS BINARY. USAGE IS BINARY. USAGE IS BINARY. USAGE IS BINARY. OCCURS 1 TO 255 DEPENDING ON LL-PARM.

01 SIZE-BUFFER 01 RET-CODE 01 RES-CODE 01 BLP-PARM. 10 10 LL-PARM GENERAL. 20

BLP-GENERAL PIC X

01 USER-CARD. 10 10 LL-CARD MSG. 20 BLP-MSG PIC X OCCURS 1 TO 255 DEPENDING ON LL-CARD. PIC 9(2) USAGE IS BINARY.

61-9

61

Using SAPUTMON to Access Business Integrity Server via External Programs Sample Programs

01 INPUT-CARD. 10 10 LL-INPUT MSG-INPUT. 20 BLP-INPUT PIC X OCCURS 1 TO 255 DEPENDING ON LL-INPUT. LINKAGE SECTION. 01 DBID1. 05 05 LEN DB PIC PIC X(2). X(2). PIC 9(2) USAGE IS BINARY.

PROCEDURE DIVISION USING DBID1. MULTIPLY 133 BY 1000 GIVING SIZE-BUFFER. DISPLAY 'DB =' DB. ******************************************* ** INIT - Send BLP parameters ** ******************************************* MOVE 'INIT' TO OPERATION-CODE. MOVE 20 MOVE TO LL-PARM. 'DHF2,3000,31,,,AS,NO' TO GENERAL. BUFFER SIZE-BUFFER RET-CODE RES-CODE. ******************************************* ** TRAN - Send the User ID and password ** ******************************************* MOVE 11 TO LL-CARD. MOVE 'USER $SYS' TO MSG. MOVE 'TRAN' TO OPERATION-CODE. CALL 'SAPUTMON' USING OPERATION-CODE USER-CARD BUFFER SIZE-BUFFER RET-CODE RES-CODE. CALL 'PRINTBUF' USING BUFFER RET-CODE RES-CODE. ******************************************* ** TRAN MOVE 9 MOVE - Send an eMerge operation TO LL-INPUT. '100,M,1' TO MSG-INPUT. ** *******************************************

CALL 'SAPUTMON' USING OPERATION-CODE BLP-PARM

MOVE 'TRAN' TO OPERATION-CODE. CALL 'SAPUTMON' USING OPERATION-CODE INPUT-CARD BUFFER SIZE-BUFFER RET-CODE RES-CODE. CALL 'PRINTBUF' USING BUFFER RET-CODE RES-CODE. ******************************************* ** END - Send an eMerge END operation ** *******************************************

61-10

Using SAPUTMON to Access Business Integrity Server via External Programs Sample Programs

MOVE 5 MOVE

TO LL-INPUT. 'END' TO MSG-INPUT. BUFFER SIZE-BUFFER RET-CODE RES-CODE.

CALL 'SAPUTMON' USING OPERATION-CODE INPUT-CARD

CALL 'PRINTBUF' USING BUFFER RET-CODE RES-CODE. FIN1. STOP RUN.

Sample Program to Print the SAPUTMON Buffer

This program prints the SAPUTMON buffer. It is linked to the calling program listed in "Sample Program to Call SAPUTMON" on page 61-9.
IDENTIFICATION DIVISION. PROGRAM-ID. PRINTBUF. ENVIRONMENT DATA WORKING-STORAGE 01 I * Print LINKAGE SECTION. 01 BUFFER. 10 10 10 10 NUM-LINES LEN-LINES FILLER LINE-ARRAY PIC 9(2) USAGE IS BINARY. PIC 9(2) USAGE IS BINARY. PIC X(129). PIC X(133) OCCURS 1 TO 1000 TIMES PIC DIVISION. DIVISION. SECTION. 9(4) USAGE IS BINARY. Buffer *

*********************************************** ***********************************************

DEPENDING ON NUM-LINES. 01 RET-CODE 01 RES-CODE PROCEDURE PIC 9(2) USAGE IS BINARY. PIC 9(8) USAGE IS BINARY. DIVISION USING BUFFER RET-CODE RES-CODE. RES-CODE= ' RES-CODE. DISPLAY '*** DISPLAY '*** DISPLAY '*** MOVE 0 TO I. PERFORM NUM-LINES TIMES ADD 1 TO I DISPLAY 'LINE=' I ' ' LINE-ARRAY(I) B u f f e r ***'. ***'. ***'.

DISPLAY 'RET-CODE= ' RET-CODE '

61-11

61

Using SAPUTMON to Access Business Integrity Server via External Programs Sample Programs

END-PERFORM. FIN1. GOBACK. END PROGRAM PRINTBUF.

61-12

Part I

Multilingual Applications

Chapter 62 Applications with More than One Language

62.1 Introduction
eMerge can be configured so that different end users of an application work with forms in different languages. All definition names (e.g. concepts, fields), documentation text, form text, and end-user error messages can be set up to appear to end users in their native language. Reports can be produced in an end users specified language. Not only the form text, but also the form orientation (i.e. left-to-right or right-toleft) can be altered according to the language for which the application is configured. Application developers can incorporate text in additional languages at the time the application forms and data objects are defined. The text for other display languages is entered on the same form as that used for the first language definition usually via property sheets. eMerge allows you to define up to 99 form-display and report languages, including DBCS (double byte character set) languages (e.g. Japanese).

Locale Language
For each application database at a site, the Locale Language must be defined. The locale language determines:

The language used when a field is defined with the DL (Dynamic Language) Language Code. Since the locale language can be changedas neededat an application site, the same application can be used in more than one language. See "Defining a Field to Display Data in the Locale Language" on page 62-17. The host code page used for the application. eMerge supports applications that use languages based on different host code pages. The initial language used for the application; i.e. the language used before the LANGUAGE command is invoked.

62-1

62

Applications with More than One Language Defining Applications for Use in More than One Language

The languages used by an application can be from the same host code page (monolocale) or from different host code pages (multilocale). Monolocale Example: In Montreal, Canada, all applications for a specific company are developed so that they can be used in both English and French. Only one host code page is needed. Example: In Basle, Switzerland, all applications for a specific company are developed so that they can be used in English, German, Italian and French. Only one host code page is needed. Multilocale Example: In Japan, applications are developed by Japanese developers for both Japanese and Chinese end users. The applications are developed so that they can be used in English, Japanese and Chinese. Two host code pages are needed.

62.2 Defining Applications for Use in More than One Language

All the language specific information that is needed to define an application to work in more than one language exists on the normal data entry forms. That is, the same definition forms are used when defining for another language as for the first language definitions. When you want a definition in another language, the definition is usually entered via a property sheet for the definition form. Before starting to work, check the status of your database with respect to language usage, with your administrator. The database must be set for the languages you may need. When you move from developing an application using a database set for one language to one set for two or more languages (or vice versa), exit the current server session and reenter it. Delete the HTML templates for the Pure definition forms.

End Users of an Application in More than One Language

When the end user works in a particular language, all text appears in the alphabet appropriate to that language, and the direction appropriate to that language (right-to-left or left-to-right). Validation of the end-user's input ensures that input is legal for that language. Field names and field values can vary in different languages and some other aspects of the form (e.g. the font and position of field names) can also vary according to language. Thus, there can be more than one version of a forma version for each language.
62-2

Applications with More than One Language Defining Concepts in More than One Language

Developers of an Application in More than One Language

When a developer works in a particular language, the development form text appears in the alphabet appropriate to that language, and the direction is appropriate to that language. System dialogs, menus, toolbars and system errors are displayed in the development language. The language used by the developer when creating applications, may be changed by the administrator. Currently, English and Japanese are supported as development languages.

62.3 Defining Concepts in More than One Language

Concepts can be defined to use more than one language. The data forms based on the concept can be displayed in any used language.

To define a concept in more than one language:

1 From Modeler, right-click the concept for which you want to define a second language and select Object > Fields.

2 Specify the other language name for the concept in the Names category of the property sheet. 3 Specify the other language names for each field in the Names category of the property sheet. Example: The Last Name field for the Employee concept may be defined with French as the second language as follows:

62-3

62

Applications with More than One Language Defining Constructors in More than One Language

To see the data form in the second language:

1 Issue the Language Second command in the Insert Command textbox:

2 Click the Test button on the Development Workbench toolbar to display the form. Example: The following figure shows the resulting Employee forms before and after issuing the Language Second command:

The data is the same, but the field titles are different. If you also want the data to be different, you must define special fields in the constructor. For details see "Defining a Field to Accept Data in More than One Language" on page 62-13.

If a particular language has been set as the current language, and a form is displayed that includes a field for which a name has not been defined in the current language, the string Unknown, in the current language, is displayed.

62.4 Defining Constructors in More than One Language

Constructors can be defined to use more than one language. The data forms based on the constructor can be displayed in any used language.

62-4

To define constructor fields in more than one language:

1 Access the Constructor form.

Applications with More than One Language Defining Constructors in More than One Language

2 With the Fields tab selected, right-click a particular field and select Detail from the pop-up menu that is displayed. The Field Definition form is displayed:

3 Define the field name in the additional languages by entering the definition name in the Names category of the property sheet. 4 Click Apply. 5 Continue to define additional language field names for all the fields in the constructor by repeating Steps 2 4.

To see the data form in an additional language:

1 Issue the following command in the Insert Command textbox: language <lang> where <lang> is the value of the Language Code field for the selected language. 2 Click the Test button on the Development Workbench toolbar. The form is displayed as you have defined it for the selected language.

62-5

62

Applications with More than One Language Multilocale ApplicationsUsing More than One Code Page

62.5 Multilocale ApplicationsUsing More than One Code Page

When the languages used for the application use more than one host code page, a dedicated database is defined for each host code page. An I/O module must be defined for each database. The databases use a shared dataset; i.e. shared catalog, shared knowledgebase, and shared databases:

For multilocale application development, eMerge supports development via several instances of Development Workbenchwhere each instance uses a different database that uses a language based on a different host code page. All the instances of Development Workbench use a shared dataset; i.e. shared catalog, shared knowledgebase, and shared databases.
62-6

Applications with More than One Language Multilocale ApplicationsUsing More than One Code Page

At runtime, eMerge dynamically resolves in which language to present the field metadata and field data to the user, based on the current language that is specified for the environment.

Example of Multilocale Support

An application is being developed for Japanese and Chinese; i.e. two host code pages are being used. Two instances of Development Workbench are invoked.

The first Development Workbench instance:

Enabled for three languages, English as the first language and Japanese as the second language, and Chinese as the third language. An English/Japanese code page (e.g. 1027/1172) is used. The development language (Pure language) is set to Japanese. The locale language is set to Japanese. All Chinese metadata fields and data are either protected or not visible. English and Japanese metadata fields and English and Japanese data are enabled and visible. The developer enters all metadata fields and data in both English and in Japanese.

62-7

62

Applications with More than One Language Multilocale ApplicationsUsing More than One Code Page

The second Development Workbench instance:

Enabled for three languages, English as the first language, Japanese as the second language, and Chinese as the third language. An English/Chinese code page (e.g. code page 836) is used. The development language (Pure language) is set to English. The locale language is set to Chinese. All Japanese metadata fields and data are either protected or not visible. English and Chinese metadata fields and English and Chinese data are enabled and visible. The developer enters all metadata fields and data in Chinese.

62-8

Applications with More than One Language Multilocale ApplicationsUsing More than One Code Page

At runtime:

When the application is run, eMerge resolves which language to present to the end-user based on the locale language setting for the environment.

Developing Multilocale Applications

Any number of languages can be specified when developing an application. The language to be used at the application site must be defined as the locale language (see your administrator to set the locale language for your database). eMerge only stores the first and second languages in the parent class. All other languages specified are stored in a dependent class. A different dependent instance is used for each additional language with the language code as its key.

62-9

62

Applications with More than One Language Multilocale ApplicationsUsing More than One Code Page

(key)

1st lang. name

2nd lang. name

Lang Lang Lang Code Code Code

name name name

Using the eMerge JOKER Feature

When the data that is entered to a particular field is different per language, define a separate field definition for each language, each identified by the code of the language appropriate to it. This is done by defining the field as a JOKER field:

62-10

To define fields that can contain language-specific data:

1 Define all the language-specific fields in the same constructor, as separate fields.

Applications with More than One Language Multilocale ApplicationsUsing More than One Code Page

The language-specific fields can only be character fields and all must have the same Size. 2 Define a joker field as a character field with the same Size as the language-specific fields. The joker field acts as a place holder and pointer to the language-specific fields. 3 Assign to the joker field the NotInClass option. 4 Right-click the joker field and select Details from the pop-up menu that is displayed. The Field Definition form is displayed. Note the field number of the joker field. 5 Access the constructor for the entity from the Navigation pane of Development Workbench. 6 Select a language-specific field. Right-click in the language-specific field and select Details from the pop-up menu that is displayed. The Constructor: Field Definition form is displayed:

7 Enter the field number of the joker field in the General Field textbox (Editing>Language category) and the language code in the Language Code textbox (Editing>Language category). 8 Repeat Step 7 for the other language-specific fields.

62-11

62

Applications with More than One Language Multilocale ApplicationsUsing More than One Code Page

9 Delete the language-specific field definitions from the operation definition. When working with DBMS Adapter for SQL, you can create the SQL table with all joker fields assigned either a null or a default value. If not, a default value is inserted by eMerge at runtime. When the end-user enters data via any data entry form which includes the operation, eMerge uses the appropriate language-specific field definition for validation of the end-user's inputbased on the current language defined for the end-user. The data is stored in the target class in the appropriate language-specific field for the current language. I/O Modules The I/O Modules for each database must be defined separately. They are not mapped to code pages not supported by the particular language version of the application.

SQL Databases

eMerge field data is stored in ANSI. An SQL database must be maintained in unicode and mapped to the appropriate code page:

The SQL field size is expanded with respect to the eMerge field size (e.g. SQL English field size = eMerge Field size * 2).

62-12

Applications with More than One Language Defining a Field to Accept Data in More than One Language

Considerations

Parallel development is not available on z/OS (no sharing on VSAM) The I/O Modules for each database must be defined separately. The I/O Modules for each database are not mapped to code pages not supported by the particular language version of the application. The development environment can not include language dependent constants in rule syntax, in query syntax, or in DBCOBOL source. A language dependent field can not be a key in a class.

Multilocale Applications at Runtime

At runtime eMerge dynamically resolves, based on the current language setting of the environment, in which language to display field metadata and field data values.

62.6 Defining a Field to Accept Data in More than One Language

Normally, the data in a multilingual application is the same, regardless of the language. Only the definition names are different. That is, the data is the same in both forms, only the field titles reflect the language change. However, if the data that might be entered to a particular field can be different per language, define a separate field definition for each language, each identified by the code of the language appropriate to it. Example: In Basle, Switzerland, all applications for a specific company are developed so that they can be used in English, German, Italian and

62-13

62

Applications with More than One Language Defining a Field to Accept Data in More than One Language

French. The Address constructor for an employee includes the city as one of the fields. The city is spelled differently, depending on the language (e.g. Geneve, Geneva).

To define fields that can contain language-specific data:

1 Define all the language-specific fields in the same constructor, as separate fields. The language-specific fields can only be character fields and the value of the Size field for all of them must be identical. 2 Define a joker field as a character field with the same value in the Size field as the language-specific fields. The joker field acts as a place holder and pointer to the language-specific fields. 3 Assign the joker field the NotInClass option. 4 Right-click the joker field and select Details from the pop-up menu that is displayed. The Field Definition form is displayed. Note the field number of the joker field. 5 Access the constructor for the entity from the navigation pane of Development Workbench.

62-14

Applications with More than One Language Defining a Field to Display Data in the Current Language

6 Select a language specific field. Right-click in the language specific field and select Details from the pop-up menu that is displayed. The Constructor: Field Definition form is displayed:

7 Enter the field number of the joker field in the General Field textbox (Editing>Language category) and the language code in the Language Code textbox (Editing>Language category). 8 Repeat step 7 for the other language-specific fields. 9 Delete the language-specific field definitions from the operation definition. When the end-user enters data via any data entry form which includes the operation, eMerge uses the appropriate language-specific field definition for validation of the end-user's input, based on the current language defined for the end-user. The data is stored in the target class in the appropriate language-specific field for the current language.

62.7 Defining a Field to Display Data in the Current Language

You can define a fieldthat is not part of a classto display data automatically according to the current language as specified by the LANGUAGE command. By assigning the CurrentLanguage option to the
62-15

62

Applications with More than One Language Defining a Field to Display Data in the Current Language

field, the field displays data with the definitions for the current languagethe data is automatically displayed using the current language character set and the data is aligned properly (right-to-left or left-to-right).

It is up to the developer to provide application logic to populate the field with the correct data based on the current language.

To display a field automatically in the current language: When working via Modeler:

1 From the Concept form, select a Field. Right-click the field and select details form the pop-up menu that is displayed. The Field Definition form for the field is displayed:

2 Assign the CurrentLanguage option (Data Type > Character category) to the field. When working with constructors: 1 Access the constructor for the entity via the navigation pane of Development Workbench. 2 Select a field and right-click in the field. Select Details from the pop-up menu that is displayed. The Constructor: Field Definition form is displayed:

62-16

Applications with More than One Language Defining a Field to Display Data in the Locale Language

3 Assign the CurrentLanguage option (Data Type > Character category) to the field.

62.8 Defining a Field to Display Data in the Locale Language

When a field is defined with the DL (Dynamic Language) Language Code, the language used for the field value is automatically set to the locale languagethe language used at an application site. See your administrator to ensure that the locale language and that the DL (Dynamic Language) Language Code are defined for your application database.

To use the dynamic language for field values: As you create your application, choose DL for the Language Code for any field that you want the field value to be in the locale language.

62-17

62

Applications with More than One Language Defining Possible Values

62.9 Defining Possible Values

The Domain Definition form includes a character at the beginning of the Meaning field. This character is used to identify the language.

Meaning is a dual language field so the field value is preceded by the Language short code. The short code is not actually displayed in any field in a form using the domain. For example, the E character identifies the language of the meanings as English.

62.10 Language-Dependent Forms

Setting Up Language-Dependent Forms
When two or more languages are used it is possible to modify the forms to fit the differences in space and layout which may be required as a result of different word lengths etc. This is managed by changing generic characteristics of the field names and field values in the version of the form for each language. The generic characteristics apply to field names and field values. They are:

font type font style size position

62-18

Applications with More than One Language Using DBCS Languages

When the GenericForGUI option is assigned to a language (see Business Integrity Server Administration Guide), any generic characteristics defined for a form, while working in the generic language, are applied to the other versions of that form for each language.

You may override the generic characteristics for a non-generic version of a form while working in that language.

Example: If English is defined as the generic language, after changing to French and changing the font type of a particular field name, the field name changes. However, all other fields names remain in the font type defined in the English form. If no generic language is specified, the first language is used.

Checking Language-Dependent Forms

Once definitions for constructor names and fields have been added for the extra languages, the resulting end-user forms should be checked to ensure that the layout looks right. The following form characteristics apply to field names and field values. They are language dependent and may be modified in the version of the form for each language: font type font style size position When the LANGUAGE command is executed the system automatically displays end-user forms in the requested language. 1 Change to the language you want to check, using the LANGUAGE command. 2 Display the form in the extra language. 3 Check the form to see if longer or shorter field names have created a need to modify the layout. 4 If changes are need, modify the form via Form Editor.

62.11 Using DBCS Languages

Included in the list of languages that are supported by eMerge are DBCS languages. A DBCS language is a language whose alphabet contains

62-19

62

Applications with More than One Language Using DBCS Languages

more symbols than can be represented by a single byte. An example of such a language is the Japanese language KANJI.

Defining DBCS Fields

If you are developing an application where one of the languages is a DBCS language, you can define two types of DBCS fields:

pure DBCS fields containing no single byte characters mixed DBCS fields that can also contain single byte characters.

Define a field as a mixed DBCS fieldonce the DBA has defined the second language as a DBCS languagevia the following: Mixed DBCS Field via the Data Type Setting the data type to DBCS is equivalent to setting the data type to Character and assigning the SecondLanguage together with the Mixed options. The field definition is automatically assigned the SecondLanguage and Mixed options. 1 Access the Constructor form and display the relevant constructor. 2 Define the field with a value of DBCS in the Data Type field. Mixed Field by Assigning Options When you define a character field as a second language field, and the second language is a DBCS language, the default is a Mixed language field. (The Mixed option is automatically assigned to the field definition.) 1 Access the Constructor form and display the relevant constructor. 2 Define the field with a value of Character in the Data Type field and assign the SecondLanguage (Data Type Properties > Character category) option. Pure DBCS Field Use the following method to define a field as a pure DBCS field (i.e. the field does not include any single byte characters). 1 Access the Constructor form and display the relevant constructor. 2 Define the field with a value of Character in the Data Type field and assign the PureDBCS option. If the field was previously defined as a mixed DBCS field, unassign the Mixed option from the field definition.

Restrictions Using a DBCS Language

The following restrictions apply specifically to an application where the second language is a DBCS language.

62-20

Applications with More than One Language Using DBCS Languages

Pattern Matching and Masking for a DBCS Field

The SBCS pattern matching characters ?, # and %, or their DBCS equivalents, behave differently, according to the string against which they are matched. See General Reference. The question mark (?) indicates a single numeric character in a character field. The hash symbol (#) indicates a single numeric character in a numeric field. The percent sign (%) indicates any single character. Pure DBCS Fields For a pure DBCS field either the SBCS characters ?, # and %, or their DBCS equivalents, can be used with the same results. Mixed DBCS Fields For a DBCS field that can contain both DBCS and SBCS characters, the results depend on whether the SBCS characters or their DBCS equivalents are used: If ?, # and % are used, they only match against SBCS characters. If the DBCS equivalents of ?, # and % are used, they only match against DBCS characters. For example, if the pattern matching string '%*' (i.e. SBCS characters) is used against a DBCS field that contains both DBCS and SBCS characters, if the first character of the field value is an SBCS character, the result is true. If, however, the first character of the field value is a DBCS character, the result is false. The opposite situation occurs if the pattern matching string (i.e. '%*') is in the DBCS equivalents. The SBCS pattern matching characters * and @, or their DBCS equivalents, behave as described in the General Reference.

DBPL1, DBCOBOL and DBREPORT

When the contents of a pure DBCS field is placed in a line for Send Line or into the field in an operation, the value must be converted to mixed format (the field can contain both DBCS and SBCS characters). The conversion is done using existing PLI functions or COBOL subroutines.

Report Separator in Queries, DBCOBOL or DBPLI

The separator used in a report must be at least of length 2, and must have a blank as the first and last characters. For example: OPTIONS SEP ' | ' valid

62-21

62

Applications with More than One Language Using a Right-to-Left Language

OPTIONS SEP '

'

valid not valid

OPTIONS SEP '| ' Rules and Queries: Moving Values into Different Type Fields

It is possible to move the value of a field into another field, whose definition is different, with the following restrictions: Source Data SBCS SBCS Pure DBCS Pure DBCS Target Data Pure DBCS SBCS Mixed DBCS no restrictions cannot be done Data may contain only SBCS characters. Data may contain only DBCS characters. Mixed DBCS no restrictions Restrictions cannot be done

Mixed DBCS SBCS Mixed DBCS Pure DBCS

You can use masking or other techniques to ensure that the data matches the character set of the destination field. For example, you can use a mask to filter out the characters from the source field that do not match the character set of the destination field. Printing DBCS Field Values For a printer which does not perform suppression of the SO and SI characters, these characters are printed as blanks. Thus, there is no need for a special setup. For a printer which does suppress SO and SI, the DBCSSUPP option must be selected in one of the following ways: Online Use the DBCSSUPP option of the PRINTER command as follows: PRINTER <printer-id> DBCSSUPP Batch Supply the following job card to the print job:

//SAPPARM DD * DBCSSUPP=ON

62.12 Using a Right-to-Left Language

When the keyboard language environment supports two languages and one of the languages is a right-to-left language, the following applies: With the environment set for one of the languages (it doesnt matter which one), entering data containing both alphanumeric and special
62-22

Applications with More than One Language Restrictions for Working with More than One Language

characters in the other language can result in the entered data string being displayed reversed after being retrieved from eMerge. To display the retrieved data as entered, enter the data string in the reverse direction.

62.13 Restrictions for Working with More than One Language

The following restrictions apply when developing and running an application using more than one language:

Keyboard Language Settings

Although a field in a form is defined for a specific language, the web browser client must change the keyboard language settings. Dynamic changes in the keyboard language settings are not supported for the web browser client. This is a known problem when working via a web browser.

Validity Checks
There is no validity check on values in global and dual fields.

DBCOBOL and DBPL1

You can only use the first language names of the eMerge definitions (constructors, fields, etc.) in DBCOBOL and DBPL1. In DBCOBOL/DBPL1 Report, the joker field can be used. At run time the field definition appropriate to the end-user's current language is substituted. See the description of the joker field in "Defining a Field to Accept Data in More than One Language" on page 62-13. The global field Current Language cannot be used in DBPL1. (In DBCOBOL use this field to find out the language in which the end-user is working.)

End-User Error Messages

Error messages which are returned by eMerge to the end user appear in the language in which the end user is working. During development, provide text in all the different languages for errors defined specifically for the application.
62-23

62

Applications with More than One Language Restrictions for Working with More than One Language

When no error message is available in the language in which the end user is working, the corresponding message in another language is displayed as follows:

If a specific alternative language has been specified for the forms current language, the message in this language is displayed. The alternate language is specified during setup of the languages for a database by the Administrator. If no site-specific alternative language has been specified, the message in the default alternative language is displayed. The default alternative language for each language supported by eMerge can be viewed in the Language Definition form (accessed by the administrator by double-clicking Languages on the Configuration tab of the navigation pane). If no alternative language has been specified, the first language message is displayed.

Queries
If more than two languages are defined at your site when a query is compiled, that query, at runtime, inserts the LANGUAGE command into the operation file (TRAN file). This command specifies the current language at the time the query was run.

62-24

Part J

Change Management

Chapter 63 Working with Change Management

The eMerge Change Management facility manages the activities associated with the development of an application so that selected development efforts can subsequently be migrated from the development database to a test or production environment. eMerge developers make changes and additions to an application via Modeler or via forms. Each update action generates an operation that updates the definitions of the application, which are stored in the eMerge knowledgebase. Operations entered into the knowledgebase can be extracted from the development database and moved to a test or production database via the internal journal, just as data can be moved. As a result of applying these operations to the target database, the target database becomes a copy of the development database. At any given stage in the development of a large application, there are numerous development activities going on simultaneously. Not all are ready for release into production at the same time. In order to make sure that each database modification belongs to a specific development activity, a task number is assigned to each development activity. When Change Management is enabled for a database, every modification made to the application must be performed under a task number. Each modification is tagged with this task number so that the Change Management Coordinator can release into production exactly those modifications that are relevant to the release.

63.1 Change Management Tasks

A task is a logical unit of work. A typical development phase includes many tasks at different levels. For instance, tasks for individual work assignments are grouped under the activity they perform. The various activities are grouped under a sub-project and the various sub-projects are grouped under a project.
63-1

63

Working with Change Management Migration Units

The task is placed in a hierarchy that reflects the structure of activities in your organization.

Task Status
The status of a task can be one of the following: open closed when the task is active. when the task is completed but has not been migrated.

InMigration When the migration checks, prior to transferring the tasks, are being performed. transferred when the task has been migrated to the target database.

No work may be done on a task that is not an open operational task.

63.2 Migration Units

A migration unit is a hierarchy of tasks that are designated for migration as a unit together. Migration units can be related in a hierarchy, that is, one migration unit can contain other dependent migration units. The main purpose of the migration unit mechanism is to categorize tasks into an autonomous unit that does not invoke online collision checking for the tasks within the unit. Online collision checking is performed between the tasks in different migration units hierarchies and also between migration unit tasks and tasks not assigned to migration units.

63.3 Checks Performed During Application Development

As development proceeds, integrity checks are performed online. The current task is checked against tasks belonging to other migration units or against tasks that are not part of any migration unit.

Types of Integrity Checks

It is forbidden for the current task to modify an eMerge object if this object was last modified by another task which is not a dependent of the current task at any level. However, if the tasks modifying the same object are part of the same migration unit, online integrity checking allows work to proceed. (The collision is nevertheless recorded and can be viewed via queries and Impact Analysis run in batch).
63-2

Working with Change Management Choosing a Task

The object can be a shared object between the two tasks or an indirect object. Shared Object Check If the task tries to update an object that was already updated by another task, then the operation fails. Indirect Object Check If the task tries to use or update an object that was impacted by the update of another object by another task, then the operation fails.

Error Messages
The following error messages or warnings can be received: Error 5619 (You are not authorized to update current object with task <task number>. No update performed.) Issued if a user tries to update an object already updated by another task which is not authorized for the current user (and are not part of the same migration unit). Error 5620 (To update current object, you must change Task No.) Issued if a user tries to update an object already updated by another one of the users allowed tasks that are part of a different migration unit or not part of any migration unit. Warning 5621 (Current object has also been updated by other tasks.) Issued if the Warning option is assigned to the active task, and the task tries to update an object already updated by other tasks. If the IngoreError option is assigned to the active task, no integrity checks are performed.

63.4 Choosing a Task

If change management is enabled for a database, you are not allowed to modify that database unless you are working under a task number. If you try to modify the application when you havent specified a task number, Business Integrity Server does not accept the modifications. For each user, the Change Management Coordinator assigns a list of tasks under which that user can work. When you are working under a particular task number, you will only be allowed to modify objects permitted under that task.

63-3

63

Working with Change Management Choosing a Task

Selecting a Task at Logon or During a User Session

When change management is in use at your site, the Tasks tab is displayed when you log on to eMerge:

It lists all tasks that are allowed for your user ID. To work under a task, right-click that tasks node and choose the Activate Task option. All subsequent operations are assigned the activated task number. During a session, if you need to switch to a different task, access the Tasks tab and choose a different task.

63-4

Part K

Development Privacy

Chapter 64 Working Under Development Privacy

If the security manager has enabled development privacy for the database, you may be restricted in the objects you can modify or even view. There are three levels of access: Forbidden The object is not accessible, i.e. is not displayed within Development Workbench or Modeler. Retrieve Update The object can be viewed, but cannot be modified. The object can be created and modified.

Access can be set at various levels: model, concept in model, field in concept, ruleset, composite, class, field. Rules are not listed in rule trace output, if they belong to rulesets whose numbers are in a range you are not allowed to access. Items on toolbars and menus are disabled when appropriate. Controls in dialog boxes are disabled according to the elements access authorization. If you switch to a different user ID during a session, your session takes on the privacy restrictions of the new user ID. When you write a query, you can specify that the query be restricted according to the access rights of the end user at run time, instead of the access rights that apply when the query was written, or the access rights of the world specified in the query definition.

64.1 Concept Model

Depending on the privacy definitions that have been set up for your user ID, access to concept models and concepts may be restricted:

Concept Model Access

Update If you have Update access for a model, but you have no allowed range of rulesets, the Rules button on the toolbar is disabled.

64-1

64

Working Under Development Privacy Concept Model

Retrieve

If you have Retrieve access for a model:

The text Read Only is added to the model title in the title bar:
Concept Model: ORDER ENTRY (Read Only)

Any changes to size and position in the model are not saved. The following are disabled: Concept Model toolbar New Entity, Weak Entity, Document, Association, Link. If you have no allowed range for rulesets, the Rules button is disabled. Modeler toolbar Model menu Edit menu Insert menu Analysis, Design, Implement

Delete, Rename

Move, Reattach, Delete, Exclude All items are disabled.

Object menu Analysis, Design Implement Stages, Rename, Change type, Delete Fields. If you have no allowed range for rulesets, Rule Model is disabled. Forbidden If access to a model is Forbidden for developers of your world, the model does not appear in the tree, so you cannot open it.

Concept Access
Update Retrieve The concept can be modified. The concept is displayed with no indication that it is restricted to Retrieve access. However, when you select a Retrieve concept, the following items are disabled: Concept Model toolbar If you have no allowed range for rulesets, the Rules button is disabled. Modeler toolbar Analysis, Design, Implement Edit menu Move, Delete, Exclude Insert menu All items are disabled.

64-2

Working Under Development Privacy Rule Model

Object menu Analysis, Design Implement Stages, Rename, Change type, Delete Fields. If you have no allowed range for rulesets, Rule Model is disabled. Forbidden If you have Forbidden access to a concept, the concept is not displayed at all. The access for an association between concepts where at least one of the concepts has Forbidden access is also Forbidden (i.e. the association is not displayed in the model).

64.2 Rule Model

Unlike the concept model, an Update rule model can include a Forbidden element. In if-then-else and call rules, a stub represents a Forbidden element. In other rule types, a Forbidden element is not displayed at all.

Rule Model Access

Update Retrieve The rule model can be modified. If you have Retrieve access for a rule model:

The text Read Only is added to the model title in the title bar:
Rule Model (Concept): A1 (Read Only)

The following are disabled: Rule Model toolbar Model menu RLST is disabled.

Delete, Rename

Edit menu Copy Special, Move, Attach, Reattach, Detach, Detach Fully, Delete, Exclude Insert menu All items are disabled.

64-3

64

Working Under Development Privacy Rule Editor Privacy Checks

Forbidden

If you have Forbidden access to a rule model, the rule model is not accessible.

Ruleset Access
Update Retrieve The ruleset can be modified. The ruleset is displayed with no indication that it is restricted to Retrieve access. However, when you select the Retrieve ruleset, the following items are disabled: Rule Model toolbar button is enabled. View menu All insert rule buttons are disabled. The RULES

Collapse, Expand

Insert menu All insert rule items are disabled. Rules are displayed with no indication that it is restricted to Retrieve access. The following items are disabled: Rule Model toolbar I, Collapse

Edit menu Copy Special, Move, Attach, Reattach, Detach, Detach Fully, Delete, Exclude View menu Forbidden Collapse, Expand

No branches are displayed within the ruleset, and the tree layout is computed without it.

Other Elements in the Rule Model

For other elements represented in the rule model, the appropriate toolbar and menu items are disabled, as needed:

Entity (Concept Root) Design Nontyped Target, Concept Target, Constructor Target, Class in Composite Target Form Root, Operation Root

64.3 Rule Editor Privacy Checks

Privacy checks are performed by the Rule Editor.
64-4

Working Under Development Privacy Rule Editor Privacy Checks

Checks for eMerge Objects based on Rule Source

Privacy is checked for various types of eMerge objects, depending on whether the rule source is a class, operation, edit operation, form, block, program, or error: Class Operation Edit Operation Form, Block, Program or Error Privacy is checked for composites, classes, and fields. Privacy is not checked for the operation. Privacy is checked for corresponding composites, classes, and fields. Privacy is checked for composites, classes, and fields. No privacy check is performed.

Checks for Fields

Privacy is checked as follows for fields: Computed field, Concept field Path field Target field No privacy check is performed. Privacy for composites, classes, and fields in the path is checked for read operation. These are fields in target classes in fetch or derivation rules. Privacy is checked for composites, classes, and fields.

Privacy Checks for Rulesets

If a rule contains Forbidden objects, then these objects are masked with question marks (???) and the whole rule appears as Retrieve. The prompt list does not contain Forbidden objects.

Privacy Checks for Stored fields and Target Fields

Stored fields must have Update access. Target fields that are target, moved, added, and subtracted must have Update access.

64-5

64

Working Under Development Privacy Inheritance of Privacy

64.4 Inheritance of Privacy

The access specified for the model is inherited by all concepts in the model, unless exceptions have been specified. In general, access to an object cannot be more restricted than access to the parent object. If a model has Retrieve access, the concepts within the model cannot have Update access. They can have Forbidden access if necessary. If a model has Update access, the concepts within the model cannot have Forbidden or Retrieve access. All concepts have Update access rights. The same rules are used for Concept and Concept Fields. If a concept has Retrieve access, the Concept Fields (210039) form is opened from the concept model to display only non-Forbidden fields.

64-6

Working Under Development Privacy Writing Queries for Runtime Privacy Definitions

64.5 Writing Queries for Runtime Privacy Definitions

By default, when security is enabled, a query is compiled to run under the privacy definitions in effect when the query was compiled, or under the definitions of the world specified in the User World field on the Query Definition form. This may not be appropriate when the query is run by users with varying security and privacy definitions. In this case, when the query runs, it should access objects according to the privacy restrictions of the user who is running the query.

To ensure that the query is restricted by the access rights of the end user at run time: Assign the RunTimeSecurity option (General category) in the Query Definition form:

64-7

64

Working Under Development Privacy Writing Queries for Runtime Privacy Definitions

When a query is run, privacy patterns are only checked if the RunTimeSecurity option is assigned. Otherwise, only the world and user privacy are checked. Use of this option is not recommended for production environments, because there is an impact on performance.

64-8

Part L

eMerge Applications via 3270-Display

Chapter 65 eMerge Applications via 3270-Display

An eMerge application that is to be accessed via 3270-display (whether it is a 3270 emulation or a 3270 terminal) is similar in most respects to an eMerge application that is accessed via i.way. In both cases, the data and logic definitions for the application are developed using Modeler and Development Workbench, as described in this manual. This part of the manual (Part L eMerge Applications via 3270-Display) provides information that is specific to applications where end users access their applications via 3270-display.

65.1 Accessing eMerge Forms via 3270-Display

The first form that is displayed after logging into eMerge can be one of the following:

The top form defined for your userID by the administrator is displayed. The top form could be a menu or a data form. For developers, the Definitions (1) menu is displayed. If no top from has been defined for your userID, the plus symbol (+) is displayed.

You can access a form directly or through a flow. All tasks described in this manual are based on the form flow.

It is recommended that you access forms via the form flow (using menus and PF keys), and not by jumping directly to the form. Via the flow, you have access to inherited PF keys and values that are transferred from form to form via the flow.

Accessing a Form via the Flow

To access a form via the flow, choose one of the following:

An option in a displayed menu. The relevant system or form-dependent PF key.

65-1

65

eMerge Applications via 3270-Display Navigating a Form

Accessing a Form Directly

To access a particular form: In the COMMAND line (or after the plus symbol), type:
Form <formnumber>

where <formnumber> is the number of the form that you want to display

65.2 Navigating a Form

Use the following keys to move about in a form: <Tab> <Shift>+<Tab> <up arrow> <down arrow> Moves the cursor to the next field. Moves the cursor to the previous field. Moves the cursor to the parallel field in the previous operation occurrence. Moves the cursor to the parallel field in the next operation occurrence.

65.3 eMerge 3270-Display Forms

The forms you create as part of an eMerge application have the following format:
form description---> SAPIENS - OPERATIONS command line------> COMMAND => FORM NAME (000000)

data area------------->

status line-----------> == INPUT ==................... S D3 $SYS 02/02/2004 11:11:57 system actions---> 1-HELP 2-SELECT 3-QUIT 4-NEW 5-CONT 6-MORE 7-BACK 8-FORW form actions----> 13-CMPS 14-OPERLIST 15-TRIGGER 24-ZOOM

65-2

eMerge Applications via 3270-Display eMerge 3270-Display Forms

Form Description
The type of the form, its name, and its number are displayed in the top line. The type of form describes how the form is used (e.g. as a menu, as an operation-based form, as an output for a query).

Command Line
eMerge commands can be entered directly in this line. Commands can be concatenated by using the semi-colon as a delimiter. Example: Entering
form 19;detail on

in the command line results in Form 19 being accessed and displayed in detail mode. You can issue the NOCOMLIN command to hide the command line from the user. When you customize your form with a frame, some elements of the command line (e.g. constants, the COMC or COMT elements) may be visible to the end user, even after assigning the NOCOMAND option. Assign the NOCOMLIN option (in addition to NOCOMAND) to prevent display of all elements in the command line. Assign the NOCOMLIN option via the FRAME DEFINITION (696) form. See Chapter 67, Customizing Form Frames.

Data Area
This area contains the information to be presented to the user. On a data form, this includes one or more data blocks. On a menu, this contains the menu options. Error messages are displayed in this area. The error messages are displayed at the bottom of this area unless the SET WINDOW ERROR command has been issued, in which case the error is displayed in a window. For details refer to the description of the command in the General Reference.

Further explanation about an error can be obtained by entering a question mark (?) in the command line while the error is displayed on the form.

65-3

65

eMerge Applications via 3270-Display System Actions

Status Line
Displays details about the following:

The operation to be performed (e.g. INPUT, MODIFY). Whether operations are accepted singly or as groups (i.e. the GROUP option or command is in use) via the letter S (for singly) or G (for groups) (e.g. S in the above figure). The databaseID (e.g. D3 in the above figure). The userID (e.g. $SYS in the above figure). The date and time (e.g. 02/02/2004 11:11:57 in the above figure).

System and Form Actions

Each form can have two sets of actions:

The set of system actions (i.e. system PF keys) that are standard functions that apply to forms. See "System Actions" below. A set of form-dependent actions (i.e. form-dependent PF keys) that are displayed at the bottom of the form.

Pressing a PF key initiates a system or form-dependent function (e.g. accessing another related form). By default the PF keys 18 (one to eight) are displayed on a separate line from the other PF keys. You can start listing the form-dependent PF keys immediately after the system PF keys (i.e. on the same line) by issuing the CONCATPF ON command or by assigning the ConcatAction option to a specific data form or menu. For details refer to the description of the command and option in General Reference.

65.4 System Actions

The following system actions are available via 3270 emulation:

65-4

eMerge Applications via 3270-Display Data Form Format

PF Number PF1 PF2

PF Name
HELP SELECT VALUE

Definition Displays eMerge context-sensitive online help (e.g. about a particular field). Displays a select form from where you can select from the displayed occurrences (see Development Workbench Getting Started). When the cursor is in the command line, the last command entered in the line is displayed, up to the last 9 commands. Returns to the calling form. If the data in the form has been changed and the contents of the form not entered to the knowledgebase (i.e. by pressing <Enter>), the system updates the knowledgebase and then quits the form. Redisplays the current form. The newly displayed form is cleared of any values that you had entered (as opposed to default values automatically displayed when the form was accessed). Control is passed to the continuation form in the flow (if one exists). Displays more options. These options are usually listed as a menu. Scrolls backwards. Additional occurrences are displayed. The key values of these additional occurrences are less than the key value of the occurrence where the cursor is. Scrolls forwards. Additional occurrences are displayed. The key values of these additional occurrences are greater than the key value of the occurrence where the cursor is. Displays a form (the zoom form) that gives more information about the current value in the field (see Development Workbench Getting Started).

PF3

QUIT

PF4

NEW

PF5 PF6 PF7

CONTINUE MORE BACKWARD

PF8

FORWARD

PF24

ZOOM

65.5 Data Form Format

The data form is used by the end user to enter data into an application. Create the application data forms by entering the relevant definitions into eMerge Pure data forms. The end user enters data into the forms you create. A form can contain blocks, text, and system and form actions. A block contains one or more sets of fields. Each set of fields is an operation. A data form can contain several blocks. Each block can contain either one or many operation occurrences. Top text, bottom text, prefix text, and

65-5

65

eMerge Applications via 3270-Display Data Form Format

suffix text are used to display comments or instructions on a form. The form-dependent actions (PF keys) are used to access additional forms in the application flow.
SAPIENS - OPERATIONS COMMAND -> Top text for first block OPERATION CODE FIELD 1 FIELD 3 DATA ENTRY SCREEN (300000)

: : _______ : _______________

FIELD 2

: ______

Bottom text for first block Top text for second block FIELD FIELD A B _ _____ _____ Prefix text for _ _____ _____ second block _ _____ _____ _ _____ _____ Bottom text for second block FIELD C _____ _____ _____ _____ FIELD D _____ _____ _____ _____

Suffix text for second block

== INPUT ==.................. S D3 $SYS 02/02/2003 11:11:57 1-HELP 2-SELECT 3-QUIT 4-NEW 5-CONT 6-MORE 7-BACK 8-FORW 13-CMPS 14-OPERLIST 15-TRIGGER 24-ZOOM

The data form example above shows a form with two blocks, text and system and form-dependent actions. In the first block, there is an operation with one occurrence. In the second block, there is an operation with four occurrences of each set of fields. The OPERATION CODE field is the first field in each operation occurrence. In the second block, the OPERATION CODE field name is not displayed. In the first block, the field titles are on the same line as the field values. In the second block, the titles appear above the column of field values.
When the field titles appear above the field values, the operation code name is not displayed.

65-6

eMerge Applications via 3270-Display Menu Format

65.6 Menu Format

A menu is a list of options to lead you to forms for defining or using an application. Top text, bottom text, header text, and option text are used to display comments or instructions. A menu option is selected by typing its number in the command line or by entering an X next to the desired option.
SAPIENS - M E N U COMMAND => Top text for menu HEADER TEXT 01 OPTION 1 02 OPTION 2 Option text for Option 3 03 OPTION 3 04 OPTION 4 Bottom text for menu MENU (300010)

== MENU ==................... S D3 $SYS 1-HELP 2-SELECT 3-QUIT 5-CONT 24-ZOOM

02/02/2003

11:11:57

The menu example above shows a menu with a menu name and number, four menu options, and some text. The header text and each menu option is displayed on a separate line.

65.7 Select and Detail Forms

A select form is a multiple-occurrence data form. On accessing the select form, all the existing occurrences for the particular field are displayed. You can select an occurrence and return to the calling form or menu. You access a select form by pressing PF2 (SELECT), with the cursor positioned on a relevant field in a data form or menu. A detail form is a single-occurrence data form. On accessing the detail form, details of the particular field are displayed. You access a detail form by pressing PF24 (ZOOM), with the cursor positioned on a relevant field in a data form or menu.

65-7

65

eMerge Applications via 3270-Display Select and Detail Forms

More information about select forms and detail forms are described in "Select and Detail Forms" on page 38-1. The control select, client select, and client detail forms are not available for 3270-display.

Specifying a Select Form and a Detail Form for a Field in a Block

You can specify a select and/or detail form for a field in a specific data form. The select form and detail form defined for the field in block override a select form and detail form defined for the field.

To specify a select form and/or detail form for a field in a block:

1 In the Form Definition form, place the insertion point on the block containing the field for which you want to specify a select form and/or a detail form and click the Fields button. The Fields in Block Definition form is displayed.

65-8

eMerge Applications via 3270-Display Select and Detail Forms

2 In the Fields in Block Definition form, place the insertion point on the field for which you want to specify a select form and/or a detail form and click the Details button. The Field in Block form is displayed:

65-9

65

eMerge Applications via 3270-Display Erasing Individual Values in the Database

3 Click the 3270 button. The 3270 Details form is displayed:

4 Enter the select and detail forms in the Select and Detail fields of the Forms subgroupbox, respectively.

Disabling a Select Form and a Detail Form for a Field in a Block

To disable a select form and/or detail form for a field in a block:

1 With the insertion point on the block needed in the Blocks groupbox on the Form Definition form, click the Fields button. The Fields in Block Definition form is displayed.

2 Place the insertion point on the field for which you want to disable a select form and/or a detail form and click the Details button. The Field in Block form is displayed. 3 In the Behavior subgroupbox, assign the NoSelection and/or NoDetailForm options: NoSelection The select form is not accessed for the field in the block. NoDetailForm The detail form is not accessed for the field in the block.

65.8 Erasing Individual Values in the Database

Erasing a field displayed on the form causes an update to the database default value. The implication of the erasure depends on whether the action is a mere form display change or if it changes the default value.

65-10

eMerge Applications via 3270-Display Issuing Commands

You can erase the value displayed in the data form. The value stored for the field in the database is replaced with:

a default value if one is defined a null value for character fields zero for numeric fields

Erasing a value in the database via a data form is controlled by the ERASEFLD command. By default, ERASEFLD is set to off.

To erase a value in the database: ERASEFLD OFF Replace the value in the field with any of the following symbols:
*

asterisk in numeric fields where the * symbol is not allowed in numeric or option fields

ERASEFLD ON Replace the value in the field with *, - or 0; or blank out the value in the field. A value must be displayed on the data form in order for its value to be erased in the database. You can change your mind before pressing <Enter>. By entering a colon (:) (whether you have blanked out the original value or replaced the original value with *,- or 0), the original value stored in the database remains unchanged.

65.9 Issuing Commands

Enter an eMerge command by typing the command in the command line and pressing <Enter>.

65.10 Viewing and Printing eMerge Listings

When you request a listing (e.g. via a query or one of the retrieval operation codes), the listing output is sent to the form unless you specifically redirect it. Use the PRINT command to redirect the output to a printer. Refer to the PRINT command in the General Reference.

65-11

65

eMerge Applications via 3270-Display Viewing and Printing eMerge Listings

65-12

Chapter 66 Forms for 3270-Display

66.1 Developing Forms for 3270-Display

Creating and modifying forms for 3270-display are not that different than creating and modifying forms for i.way-display. Most of what is needed is described in Part E Presentation. The information specified here covers the differences. The following is the recommended order when creating a form. Each step is described in greater detail in subsequent sections.

To create a form for 3270-Display:

1 Define the form (i.e. create and modify) using a Development Workbench via the Form Definition form. See page 66-4 for more information. 2 Define form characteristics. See page 66-8 for more information. 3 Define one or more blocks. Enter block details for as many blocks as are needed. Each block defines an operation, program, or query that is being used by the form. See page 66-9 for more information.

4 Define field in block characteristics. See page 66-13 for more information. 5 Define form-dependent actions (e.g. calling another form). See page 66-20 for more information. 6 Define entry and/or exit commands. See page 66-21 for more information. 7 Display the form to evaluate how it looks so far via a 3270-terminal emulation session. The session is connected to the same database on Business Integrity Server as the Development Workbench session described in Step 1. See page 66-22 for more information. 8 Customize the display of the form. See page 66-22 for more information.

66-1

66

Forms for 3270-Display Differences for 3270-Display and i.way-Display

66.2 Differences for 3270-Display and i.way-Display

The main differences to note when creating forms for 3270-display (instead of for i.way-display) are:

Only data forms and menus can be used. The other form types are not supported for 3270-display. Do not use Form Editor for the form; Form Editor has no impact on the 3270-display. Instead, forms are created and modified via the Form Definition form. Templates are not supported. Therefore, the following should be noted:

When working via Modeler, the concept model should be defined without a template. However, if the implemented data objects are to be used for 3270-display and for i.way-display, then the model can be defined with a template. The forms for the 3270-display should be created without a template. When creating a form via the Form node in the Presentation tab, no template should be defined for the form via the Data Form form. Note that form frames can be defined and assigned to an application by defining the application as a world. Form frames are a type of template for 3270-display forms. See "Customizing Form Frames" on page 67-1.

The GUI option should be unassigned for any 3270-display formno matter which working path you are using (i.e. via the concept model or via the Form node). External components cannot be defined for 3270-display forms. Do not check the form display via Development Workbench. Displaying the form via Development Workbench does not give a true picture of the form.

66.3 Examples of Data Forms for 3270-Display

A data form for 3270-display (like those for i.way-display) can contain blocks, text, and system and form actions. A block contains one or more sets of fields. Each set of fields is an operation. A data form can contain several blocks. Each block can contain either one or many occurrences. Top text, bottom text, prefix text, and suffix text are used to display comments or instructions. The form-dependent actions (PF keys) are used to access additional forms in the application flow.
66-2

Forms for 3270-Display Examples of Data Forms for 3270-Display

The following data forms are simple examples of 3270-display forms: Single-Operation Form with One Occurrence
SAPIENS - OPERATION COMMAND => OPERATION CODE EMPLOYEE NO DEPT NO :_ :____ :____ EMPLOYEE NAME HIRE DATE :_________________ :__________ ZOOM EMPLOYEE-EMPLOYEE (330001-003300)

==

INPUT

==.......................... S UY $SYS

02/02/2003

15:04:32

1-HELP 2-SELECT 3-QUIT 4-NEW 5-CONT 7-BACK 8-FORW 10-EMPLOYEE

Single-Operation Form with Multiple Occurrences

SAPIENS - OPERATION COMMAND => EMPLOYEE NO E _ _ _ _ _ _ _ _ _ _ == ____ ____ ____ ____ ____ ____ ____ ____ ____ ____ ____ INPUT EMPLOYEE NAME DEPT NO

EMPLOYEE

(330000-00330)

HIRE DATE

_________________ ____ __________ _________________ ____ __________ _________________ ____ __________ _________________ ____ __________ _________________ ____ __________ _________________ ____ __________ _________________ ____ __________ _________________ ____ __________ _________________ ____ __________ _________________ ____ __________ _________________ ____ __________ ==.......................... S UY $SYS 02/02/2003 05:35

1-HELP 2-SELECT 3-QUIT 4-NEW 5-CONT 7-BACK 8-FORW 10-EMPLOYEE

66-3

66

Forms for 3270-Display Define the Form

MultipleOperation Form

SAPIENS - OPERATIONS COMMAND => OPERATION CODE EMPLOYEE NO DEPT NO CHILD NO CHILD NAME BIRTH DATE _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ == INPUT :_ :____ :____

EMPLOYEE CHILD

(330100)

EMPLOYEE NAME HIRE DATE

:_________________ :__________

==.......................... S UY $SYS

02/02/2003

15:06:04

1-HELP 2-SELECT 3-QUIT 4-NEW 5-CONT 7-BACK 8-FORW

66.4 Define the Form

Working via Modeler
When working via Modeler, add the forms to the form list for the concept design. 1 In the model, right-click the implemented concept for which you wish to define forms for 3270-display. 2 Choose Object > Concept Design from the pop-up menu to display the Concept: Design form.

66-4

Forms for 3270-Display Define the Form

3 Click the Forms button. The Constructor Forms form is displayed. This form lists the forms that were created automatically when the concept was implemented and any forms created for the concept design.

4 In the list of forms, enter a name for the new form you wish to define. 5 Enter the number of occurrences that are to be displayed in the Occ field according to the following values: -1 0 The maximum number possible that fits onto the form are displayed. One occurrence is displayed.

positive integer The number of occurrences that are displayed. 6 If you are creating a form for a root concept, assign the NoDisplay option. 7 Click Apply.

66-5

66

Forms for 3270-Display Define the Form

8 With the insertion point on the new form name, click the FormDef button to display the Form Definition form:

66-6

Forms for 3270-Display Define the Form

Working via the Form Node

When working via the Form node, add the form to the tree control on the Presentation tab. 1 On the Presentation tab, choose Forms > New Data Form. The Data Form form is displayed:

2 Enter the number and name for the form in the Form No. and Name fields. 3 Choose no template (blank value) in the Template field. 4 Click Apply. 5 Unassign the GUI option.

66-7

66

Forms for 3270-Display Define Form Characteristics

66.5 Define Form Characteristics

1 With the form displayed in the Form Definition form, ensure that:

There is no Template defined for the form. The GUI option is unassigned.

2 In the first block, click the Advanced button. The Form Advanced form is displayed:

3 Assign the ConcatAction option to display the form-dependent actions starting immediately after the system actions (i.e. starting in the first line). Without the option assigned, the form-dependent actions are displayed starting in the second and third lines. Assigning the ConcatAction option:

Reduces the part of the form frame used to display the actions, and thus enlarges the part available for form content. Enables more actions to be displayed. Three lines are allocated for actions. Thus, if the number of actions defined for a form exceeds three lines, the last actions are not displayed.

The ConcatAction option is not inherited from a calling form. However, if no form-dependent actions have been defined for the called form, the form-dependent actionsthat are inherited from the calling formare displayed on the called form as concatenated. Issue the CONCATPF command to specify concatenation for all forms. Issue the SET PF SYS NODISPLAY command to prevent the display of the system actions so that more space becomes available.
66-8

Forms for 3270-Display Define Blocks

4 Assign the NoCommand option so that the command line is not displayed on the form (i.e. the user cannot issue commands which require the command line), and so that an extra line is available for form content. If you customize your forms with a frame (see "Customizing Form Frames" on page 67-1), some elements of the command line (e.g. constants, the COMC, or COMT elements) may be visible even if the NoCommand option has been assigned. Assign the NOCOMLIN option (via the FRAME DEFINITION (696) form) to prevent display of all elements in the command line. The NoCommand option is not inherited from a calling form. Issue the COMMLINE OFF command to remove the command line for all forms. Issue the QUITTOP ON command for a user or world for whom the NoCommand has been assigned to the top form. This enables the user to quit an eMerge session by clicking the Quit button in the top form. 5 Click OK to return to the Form Definition form.

66.6 Define Blocks

For forms defined via Modeler, at least one block is added automatically when the form is created. Use the procedure below to add more blocks to the form. For forms defined via the via the Form node, all the blocks must be added using the procedure below.

To insert a block:

1 With the form displayed in the Form Definition form, put the insertion point on an empty row in the Blocks groupbox. 2 In the Block No. field, define the block number that uniquely identifies the block in the form. The order of the blocks on the form is defined by the order of the block numbers. Use block numbers in tens (e.g. 10, 20, 30...) to allow for the addition of others later on. 3 Specify the operation, program or query that the block is to contain. For each, the field is the operation, program or query number, respectively. 4 Specify the number of occurrences you need in the Occ field according to the following values: -1 The maximum number possible that fits onto the form are displayed.

66-9

66

Forms for 3270-Display Define Blocks

One occurrence is displayed.

positive integer The number of occurrences that are displayed. Example: In the following form, the first block has one occurrence and the second block has eight occurrences:
SAPIENS - OPERATIONS COMMAND => OPERATION CODE EMPLOYEE NO EMPLOYEE NAME DEPT NO HIRE DATE NO :_ :____ :_________________ :____ :__________ CHILD CHILD NAME BIRTH DATE _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ == INPUT ==.......................... S UY $SYS 02/02/2003 15:24:18 EMPLOYEE CHILD (330100)

1-HELP 2-SELECT 3-QUIT 4-NEW 5-CONT 7-BACK 8-FORW

5 Assign TitlesOn (if required) to place the field names above the fields rather than on the side of the fields. This is useful for multi-occurrence blocks. 6 Assign any other options required and click Apply. The new block is displayed on the form. 7 Repeat steps 1 to 6 if more than one block is needed in the form.

66-10

Forms for 3270-Display Define Blocks

To extend the block definition:

1 With the insertion point on the block needed in the Blocks groupbox on the Form Definition form, click the Details button. The Block Definition form is displayed:

2 Modify and extend in any way needed the definition of the block. Note the following:

Block Type and the Mandatory option are not supported for 3270display forms. The options listed in the 3270 subgroupbox are for 3270-display forms: Beside The block is displayed to the right side of the preceding block instead of underneath it (the default situation). Note there must be enough space available on the form for the display of the block (between the end of the last field or Suffix Text displayed in the preceding block and the end of the form).

66-11

66

Forms for 3270-Display Define Blocks

This option enables the maximum number of blocks to be displayed on a single form. It is normally assigned for end user convenience, to display related data in the same form, avoiding the need to scroll (forward and backward) or invoke other forms in order to access more occurrences. It is also used to show matching classes in relation to each other (e.g. employees in relation to job positions for a department).

Any field with a size exceeding the width of the block space is automatically ignored (i.e. is not displayed), and truncated is displayed on the bottom of the form.

Compact Only one row for each occurrence is displayed for a block assigned the TitlesOn option. Wrapped-around fields, that are displayed in another line are not displayed. The wrapped-around fields are displayed when the DETAIL ON command is issued. FillNames The gap between the end of the field name (when the field name is shorter than 16 characters) and the beginning of the field value is filled with periods instead of blanks. ShowOPCodeTitle The operation code title is displayed. It is displayed even if the block is assigned the TitlesOn option. MandatoryOnEnter The user must update at least one occurrence of the block, before being allowed to continue in the form flow. However, the user may quit from the form or invoke other forms by using one of the form actions (except the Continue or More system actions). To disable the use of the Quit button when the block is assigned MandatoryOnEnter, the Quit button should have Ignore assigned. If the More button is required before the block is entered (updated), a form-dependent action must be defined that invokes the required function or set of functions. ChangeAfterEdit For compatibility with applications developed before V4. Neutralizes the AUTOCHAN OFF command in this block only.

66-12

Forms for 3270-Display Define Field in Block Characteristics

66.7 Define Field in Block Characteristics

1 With the insertion point on the block needed in the Blocks groupbox on the Form Definition form, click the Fields button. The Fields in Block Definition form is displayed:

2 Modify and extend in any way needed the definition of any field. 3 If needed, change the title that is displayed for a field by entering a name in the Displayed Name field. Use the following special characters to format the displayed name: / The slash forces a line break when the TitlesOn option is assigned to the block. @ The at sign represents a hard space insuring that a line break does not occur. (eMerge automatically breaks long field names over more than one line.)

The title can be changed on a form-by-form basis here via the Fields in Block Definition form or globally via an operation definition.

66-13

66

Forms for 3270-Display Define Field in Block Characteristics

4 For any field that needs further characterization, with the insertion point on the field, click the Details button. The Field in Block form is displayed:

5 Use this form to define characteristics of the fields appearing in an operation, query, or program specified in the block. When the same field (with the same field number) appears more than once in the operation, the correct field occurrence is identified by using the Oper. Checkset field for verification. The same occurrence of the field in the operation (having the same Oper. Checkset field value) may be defined here more than once for different purposes. In this case, the different references are identified by the Stored Field which must have a different value in each reference. You can establish possible values for the Operation Code field in the block, so that only a subset of the operation codes can be used in this block; e.g. only the Edit operation is allowed so that the block is view only. The Meaning and the Explanation of the values are always taken from the global definitions in the Possible Values form and cannot be overridden. Note that the ValueInBox, Password, and OptButnNoFrame options are not supported for 3270-display forms. 6 To hide the display of the field value, assign the Invisible option.

66-14

Forms for 3270-Display Define Field in Block Characteristics

7 To specify field details that are only applicable for 3270-display forms, click the 3270 button in the Field in Block form. The 3270 Details form is displayed:

Horizontal Pos The column in the line at which the first character of the field titleif it appears in the line (Inrow format) or field value (TitlesOn format)is displayed. The position is in the same line in which the field would have appeared with standard positioning. If the field length is such that the field cannot be entered (including its name, value and trailer, if one exists), on the current line, it starts on the next line, at the beginning of the block. If the specified position in the line overlaps some previous field on the form, it is considered as a request for positioning, in the same position, in the next line. Blanks are filled from the standard position for the field up to the specified position in the next line, where the field starts. The Horizontal Pos has a special meaning in the following cases: Multiple Occurrences in a Line This is the case where the Occur. In Line field contains a value greater than 1. The value entered (in Horizontal Pos refers only to the first block column which is then entirely duplicated according to the value of the Occur. In Line field. Relative Positioning This is the case where RelativePosition is assigned to the field. The value entered in Horizontal Pos specifies the position, relative to the last character of the preceding field in the same line. When the field is (or becomes) the first field displayed in the line (or in the block occurrence), the value in Horizontal Pos is relative to the
66-15

66

Forms for 3270-Display Define Field in Block Characteristics

beginning of the block occurrence displayed on the form, taking into consideration the Offset or Occur Distance space. When the default value (zero) is used in Horizontal Pos, the relative positioning is used, and the fields are displayed in sequence in the line (not when data is displayed in columns in Titles In mode). A distance of two spaces is automatically generated between the field and the field which precedes it in the same line (the same result is obtained when a value of two is entered in Horizontal Pos). The distance between the displayed fields may be reduced to one space by entering value of one in Horizontal Pos and assigning RelativePosition to the field. When the distance is reduced to a single space in TitlesOn mode, the AUTOSKIP command is not available (it is always OFF) for the previously displayed field on the form, regardless of the value previously given in an AUTOSKIP command. Beside Option Assigned to the Block If this block is placed beside another block on the form, the horizontal position is from the beginning of the block, not from the beginning of the form. Length in Form A short length for the field value on a form. If the Length In Form is defined, the field may only be used for retrieval. Definition of Length In Form automatically makes the field protected and available for retrieval only. The use of Length In Form is not recommended for key fields. Length In Form may be defined for the following data types:

Numeric Fields (N): Binary, PackedDecimal or ZonedDecimal. Character Fields (C): Data Type Character or DualLanguage.

The field is truncated if its output length exceeds Length In Form. The truncation algorithm is different for each of the two data types. For character fields if the output length exceeds its Length In Form, the end of the field is truncated. For numeric fields, if the output length exceeds its Length In Form, the field is truncated according to the following sequence of operations. When the truncation step is sufficient to display the number in the specified length, the truncation is stopped. The result as displayed is the longest string which does not exceed the Length In Form. Thus, the minimum number of truncation operations are performed: 1. Remove left fill and then right fill characters, e.g. ' 1 ' is converted to 1. 2. Remove trailing zeros from the decimal part, e.g. 12.345000 is
66-16

Forms for 3270-Display Define Field in Block Characteristics

truncated to 12.345. 3. Remove leading zeros, e.g. -000,123,456 is converted to -123,456. 4. Remove commas, e.g. 1,234,567 is converted to 1234567. 5. Round the decimal fraction by rounding the digits of the fraction to fit into the Length In Form. e.g. 12.3457 is rounded to 12.346 and so on. 6. Present the number in rounded thousands, e.g. 1234567 is rounded to 1235K or 1234.6K 7. Represent as millions, e.g. 12345K is rounded to 12.3M or 12M. 8. If all the above steps are not sufficient, the required string cannot be constructed. The value is represented as: @@@...@. This algorithm rounds .45 up and rounds .44 down, e.g. 19.45 rounds to 19.5 while 19.44 rounds to 19.4. Example: 1,234,56.78 to a field length of 8 is displayed as 123456.8.

Exception: 999.9 is to be displayed in a field of length 3. The field when rounded would be 1000 which exceeds the field length. But, since it is less than a thousand it cannot be represented as thousands (K's). In this special case, the figure is displayed as 999. SeparateTrailer The fields trailer appears on a separate line. Instead of being appended to the field in the same line of the field's value, it starts on the following line and nothing else appears on the trailer's line. This is useful for entering a line of text in between the operation's fields. If the field was defined without a trailer, an empty line follows the field's line on the form. This is the means by which a space line may be defined between fields on the form. This option is not allowed for a block assigned with TitlesOn. SeparateGroup A grouping field is displayed as its subfields. The group name is used as the title. SeparateGroup causes the operation in the block, which includes this grouping field, to format this field as multiple separated subfields. The subfields are displayed on the form and used, separately, for data entry and for displaying data extracted from the database. This is regardless of how the data is stored in the databasein a single grouping field or in multiple subfields. If TitlesOn is assigned on the block containing the subfields, the fields are separated by a single space. If TitlesOn is not assigned and separators are not defined between the subfields, the fields are separated by two spaces. SeparateGroup is used to override the default option where the grouping field is formatted as a single field.
66-17

66

Forms for 3270-Display Define Field in Block Characteristics

In both cases (single and multiple fields display), the corresponding fields (grouping field or subfields) are displayed with a common title (which is the grouping field name or the Displayed Name if defined). When a grouping field is defined in various blocks of a form with the Common assigned, SeparateGroup should be assigned only in the block where it is to be used (i.e. only where the formatting of the field as subfields is required). The subfield feature is not available for blocks containing programs or queries. When SeparateGroup is assigned, the separate display of the sub-fields takes place only in the specific form defined here. If this option is required in every form where this grouping field is to be formatted, SeparateGroup must be assigned to the grouping field global definition. NoDetailName The displayed name for a grouped field is not displayed in a detail form. Grouped The field name (or title) of the first field in the group is displayed as the title of all the groups fields. The field title of the first field in the group is displayed as the title of all the fields in the group (i.e. a set of contiguous fields in the operation is assigned with Grouped). If TitlesOn is assigned, the group title is displayed centered above the group of field values. Example:

If TitlesOn is not assigned, the group title is displayed in front of the group of field values. Example:

If a Displayed Name is defined for a field which is not the first in the group, then this field is the first field in a new group. The title of the field is the text of the Displayed Name for the next group.
66-18

Forms for 3270-Display Define Field in Block Characteristics

Example:

RelativePosition The value set in the Horizontal Pos field. Specifies the number of spaces between the field and the previous field. Default is 1. The Horizontal Pos field in this form must not be defined with the default value (zero). If RelativePosition is assigned, the value of Horizontal Pos specifies the position for the first character of the field, relative to the last character of the preceding field in the same line. The value defines the distance between the field and the field which precedes it in the same line. When the field is (or becomes) the first field displayed in the line (or in the block occurrence), the value in Horizontal Pos is relative to the beginning of the block occurrence displayed on the form (taking into account the Offset or Occur Distance space). When the distance between the displayed fields is reduced to one space in a TITLESON mode (i.e. value 1 is entered in Horizontal Pos and RelativePosition is assigned), the AUTOSKIP command is not available (is OFF) for the previously displayed field on the form (regardless of the value previously given in an AUTOSKIP command.) When the multiple block occurrences in line feature in used in the block, the value entered in the Horizontal Pos field and RelativePosition apply for all the block occurrences displayed on the form. 8 To display the field name, field value, and/or trailer intensified, assign the IntensifyName, IntensifyValue, and/or IntensifyTrailer option, respectively. 9 To define the colors for common fields, field names, field values, text and/or trailers, select the colors in the 3270 Presentation Colors category. 10 To display a field according to the issuing of the DETAIL command, assign the following options:

66-19

66

Forms for 3270-Display Define Form-Dependent Actions

Detail

The field is displayed if DETAIL ON is issued. If DETAIL OFF is issued, the field is ignored and is not displayed on the form. The field is not displayed if DETAIL ON is issued. If DETAIL OFF is issued, the field is displayed on the form.

NoDetail

66.8 Define Form-Dependent Actions

1 With the form displayed in the Form Definition form, click the Actions button. The Form/Menu Actions form is displayed:

2 Use this form to specify form-dependent actions and the command, called form, or called block each action invokes. The actions normally apply to all of the forms called forms, unless a different action having the same action number is defined. The inheritance of an action can be limited by assigning LocalAction or in situations where the action is inherited and the current form (where the action should be inherited) is also the called form for the action. In this case, the action is ignored in the current form (i.e. it is not displayed and its command does not function). Note that when the action is ignored, it is only ignored in the current form and not in other forms called from either the parent form or from the current form. 3 Click the Details button to display the Action Definition form. Use this form to specify more information about the action. Note that the Displayed Names, Hyperlink, and Tool Tips subgroupboxes, the ClientOnly
66-20

Forms for 3270-Display Define Entry and Exit Commands

option, and the Client Block field are not supported for 3270-display forms.

66.9 Define Entry and Exit Commands

You can define commands that affect the working environment for a form on accessing (i.e. entry) and on exiting a form (i.e. exit). The entry and exit commands specified for a form override any initial commands specified for a user or for a user's world. By default, the commands specified as entry commands are inherited by all called forms. The exit commands are activated when leaving the form where they are defined. Ensure that the exit commands, which are activated on leaving the form, complement the entry commands, which are activated on accessing the form.

To define entry and/or exit commands for a form:

1 With the form displayed in the Form Definition form, click the EntExCmnd button. The Form/Menu: Entry/Exit Commands form is displayed:

2 Specify the entry and exit commands you want (e.g. GROUP ON in the Entry Commands field and GROUP OFF in the Exit Commands field).

Execution commands (e.g. Compile) and the Language command must not be defined.

66-21

66

Forms for 3270-Display Evaluate Initial Form Display

66.10 Evaluate Initial Form Display

The final step in creating a form is to look at the initial form display that has been created and evaluate its clarity and ease of use. Plan any improvements to the layout, user friendliness and completeness of the form. Changes to the form are described in "Customizing the 3270Display" on page 66-22. When you are planning changes for a particular form, you must also consider whether these changes apply to other forms. You can change the way in which the data is presented to the user at different levels:

Field in block level: In a particular block on a particular form only. Operation level: In an operation, so that the change applies whenever that operation is invoked by any block. Field level: In a concept, where the definition of a field is held for the whole knowledgebase, so that the change applies wherever the field is used.
Possible values for a field can only be defined at this level via a domain when working via Modeler.

Example: Assigning the Quantity option to a field on the concept level adds the appropriate commas or periods to separate the thousands in a numeric field in every form where the field appears. Example: Usually, the name that is displayed for a field is the name defined in the Concept Fields form. The name can be changed for all forms invoking a particular operation.

To check the form display: Check the form display via a 3270 terminal or 3270 emulation.

66.11 Customizing the 3270-Display

You can customize the 3270-display forms via the Form Definition form and the forms accessed from it. The following changes to the 3270display are described in this chapter:

To offset the block. See page 66-23 for more information. To change the number of columns in a single-occurrence block. See page 66-23 for more information. To change the number of columns displayed in a multi-occurrence block. See page 66-26 for more information.

66-22

Forms for 3270-Display Offsetting the Block

To change the number of occurrences displayed. See Step 4 on page 66-9. To display blocks side by side. See page 66-27 for more information. To add text around a block. See page 66-28 for more information. To define colors for 3270-display forms. See page 66-32 for more information.

66.12 Offsetting the Block

1 With the form displayed in the Form Definition form, put the insertion point on the block needed in the Blocks groupbox and click the Details button. The Block Definition form is displayed. 2 Ensure that the TitlesOn option is assigned for the block. 3 Enter the number of spaces on the form that you want to shift the block to the right in the Offset field. Example:
COMMAND => OPERATION CODE EMPLOYEE NO DEPT NO NO :_ :____ :____ CHILD CHILD NAME BIRTH DATE _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ == INPUT ==.......................... S UY $SYS 02/02/2003 15:14:12 EMPLOYEE NAME HIRE DATE :_________________ :__________

The second block is offset by ten in this form:

EMPLOYEE CHILD (330100)

SAPIENS - OPERATIONS

1-HELP 2-SELECT 3-QUIT 4-NEW 5-CONT 7-BACK 8-FORW

66.13 Changing the Number of Columns in a Single-Occurrence

66-23

66

Forms for 3270-Display Changing the Number of Columns in a Single-Occurrence Block

Block
1 With the form displayed in the Form Definition form, put the insertion point on the block needed in the Blocks groupbox and click the Details button. The Block Definition form is displayed. 2 Ensure that the TitlesOn option is not assigned for the block. 3 Enter a value in the No. of Columns according to the following: 0 The fields in the occurrence are displayed one after another (according to their order in the operation definition) using the minimum space necessary. The Name Size field is ignored. The fields are displayed in a single column. The default value. The fields are displayed in two columns. The fields are displayed in three and four columns, respectively. When you use three or four columns, decrease the Name Size field from its default size of 16, so that short field titles are not padded with so many blanks. If the title does not fit into the value in the Name Size field, the full name is displayed.

1 2 3 or 4

Example: The first block has one column:

66-24

Forms for 3270-Display Changing the Number of Columns in a Single-Occurrence Block

SAPIENS - OPERATIONS COMMAND => OPERATION CODE EMPLOYEE NO EMPLOYEE NAME DEPT NO HIRE DATE NO :_ :____ :_________________ :____ :__________ CHILD CHILD NAME

EMPLOYEE CHILD

(330100)

BIRTH DATE

_ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ == INPUT ==.......................... S UY $SYS 02/02/2003 15:24:18

1-HELP 2-SELECT 3-QUIT 4-NEW 5-CONT 7-BACK 8-FORW

The first block has two columns:

SAPIENS - OPERATIONS COMMAND => OPERATION CODE EMPLOYEE NO DEPT NO NO :_ :____ :____ CHILD CHILD NAME BIRTH DATE _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ == INPUT ==.......................... S UY $SYS 02/02/2003 15:14:12 EMPLOYEE NAME HIRE DATE :_________________ :__________ EMPLOYEE CHILD (330100)

1-HELP 2-SELECT 3-QUIT 4-NEW 5-CONT 7-BACK 8-FORW

66-25

66

Forms for 3270-Display Changing the Number of Columns Displayed in a Multi-Occurrence Block

66.14 Changing the Number of Columns Displayed in a MultiOccurrence Block

Normally, the occurrences in a block are displayed one under the other, in a single column. You can define a block such that the occurrences are displayed in more than one column. When occurrences are displayed one after the other, the number of occurrences equals the number of lines used to display them. When operation occurrences are displayed side by side, the number of occurrences is the number of lines multiplied by the number of occurrences per line. 1 With the form displayed in the Form Definition form, put the insertion point on the block needed in the Blocks groupbox and click the Details button. The Block Definition form is displayed. 2 Enter the number of columns you want in the Occur. in Line field. 3 Enter the distance you want between the fields in the Occur Distance field. Example: The occurrences in the second block are displayed in two columns in the following form:
SAPIENS - OPERATIONS COMMAND => OPERATION CODE EMPLOYEE NO DEPT NO CHILD NO CHILD NAME BIRTH DATE _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ == INPUT :_ :____ :____ EMPLOYEE NAME HIRE DATE CHILD NO CHILD NAME BIRTH DATE _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ 02/02/2003 15:12:32 :_________________ :__________ EMPLOYEE CHILD (330100)

==.......................... S UY $SYS

1-HELP 2-SELECT 3-QUIT 4-NEW 5-CONT 7-BACK 8-FORW

66-26

Forms for 3270-Display Displaying Blocks Side by Side

66.15 Displaying Blocks Side by Side

Normally, blocks are defined such that they are displayed one under the other. You can also define the blocks such that a block is positioned to the side of the one preceding it:

First Block Second Block Default situation

First Block

Second Block

Blocks side by side

1 With the form displayed in the Form Definition form, put the insertion point on the block needed in the Blocks groupbox and click the Details button. The Block Definition form is displayed. 2 Assign the Beside option to the block. Example: The second block is displayed at the side of the first block in the following form:
SAPIENS - OPERATIONS COMMAND => OPERATION CODE EMPLOYEE NO EMPLOYEE NAME DEPT NO HIRE DATE :_ :____ :_________________ :____ :__________ CHILD NO CHILD NAME BIRTH DATE _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ _ ____ _________________ __________ == INPUT ==.......................... S UY $SYS 02/02/2003 15:28:19 EMPLOYEE CHILD (330100)

1-HELP 2-SELECT 3-QUIT 4-NEW 5-CONT 7-BACK 8-FORW

66-27

66

Forms for 3270-Display Adding Text Around a Block

66.16 Adding Text Around a Block

You can add text around a block as top text (above the block) and bottom text (below the block), or as prefix text (to the left of the block) and suffix text (to the right of the block).
SAPIENS - OPERATIONS COMMAND -> Top text for first block OPERATION CODE FIELD 1 FIELD 3 : : _______ : _______________ FIELD 2 : ______ DATA ENTRY SCREEN (300006)

Bottom text for first block Top text for second block FIELD A _ _____ Prefix text for second block _ _____ _ _____ _ _____ Bottom text for second block == INPUT ==.................. S D3 $SYS 02/02/2003 11:11:57 FIELD B _____ _____ _____ _____ FIELD C _____ _____ _____ _____ FIELD D _____ _____ _____ _____ Suffix text for second block

1-HELP 2-SELECT 3-QUIT 4-NEW 5-CONT 6-MORE 7-BACK 8-FORW 13-CMPS 14-OPERLIST 15-TRIGGER 24-ZOOM

Adding Text Above and Below a Block

Top text and bottom text are useful for instructing a user how to proceed. The text lines may only be specified for blocks containing an operation, a query, or a program.

To add text or messages that appear at the top or at the bottom of a block on a form:

1 With the insertion point on the block needed in the Blocks groupbox on the Form Definition form, click the Details button. The Block Definition form is displayed. 2 Click the TopBottom button. The Block:Top/Bottom Text form is displayed:

66-28

Forms for 3270-Display Adding Text Around a Block

3 Enter the text to be displayed at the top of the block in the Top Text groupbox. You can scroll to add more than three lines of text. 4 Enter the text to be displayed at the bottom of the block in the Bottom Text groupbox. You can scroll to add more lines of text. 5 To put space between blocks, insert blank lines as bottom text to the top block of the data entry form, or top text to the next block of the data entry form. 6 Ensure that the text does not overflow the available room on the physical form. 7 To define the top text or bottom text characteristics: Click the Details button in the Top Text groupbox. The Block: Top Text Details form is displayed:

66-29

66

Forms for 3270-Display Adding Text Around a Block

Click the Details button in the Bottom Text groupbox. The Block: Bottom Text Details form is displayed:

8 To display the top or bottom text only when the DETAIL ON command is issued, assign the Detail option. Conversely, to display the top or bottom text only when the DETAIL OFF command is issued, assign the NoDetail option. 9 To display the top or bottom text as highlighted text, assign the Intensify option.

Adding Text to the Sides of a Block

Prefix text and suffix text can be used for prompting the user about specific fields and/or the way to handle data entry. Prefix text and suffix text may only be specified for blocks containing an operation, a query, or a program.

66-30

Forms for 3270-Display Adding Text Around a Block

To add text or messages that appears to the left (prefix text) or to the right (suffix text) of a block in a form:

1 With the insertion point on the block needed in the Blocks groupbox on the Form Definition form, click the Details button. The Block Definition form is displayed. 2 Ensure that the TitlesOn option is assigned to the block. 3 If you are adding prefix text, provide space for prefix text by defining an Offset value. The minimum value that can be defined in the Offset field is 0 (no prefix text); the maximum is 30. If the prefix text length exceeds the Offset value, the text is truncated. 4 Click the PrefixSuffix button. The Block: Prefix/Suffix Text form is displayed:

5 Enter the text to be displayed at the left of the block in the Prefix Text groupbox. You can scroll to add more than three lines of text. 6 Enter the text to be displayed at the right of the block in the Suffix Text groupbox. You can scroll to add more than three lines of text. 7 Ensure that the text does not overflow the available room on the physical form. 8 To define the prefix text or suffix text characteristics: Click the Details button in the Prefix Text groupbox. The Block: Prefix Details form is displayed:

66-31

66

Forms for 3270-Display Defining Colors for 3270-Display Forms

Click the Details button in the Suffix Text groupbox. The Block: Suffix Details form is displayed:

9 To display the prefix or suffix text only when the DETAIL ON command is issued, assign the Detail option. Conversely, to display the prefix or suffix text only when the DETAIL OFF command is issued, assign the NoDetail option. 10 To display the prefix or suffix text as highlighted text, assign the Intensify option.

66.17 Defining Colors for 3270-Display Forms

The administrator can set the default colors to be used for all 3270display forms. The colors that are set include the defaults for menus, form frames, form blocks, form fields, error messages, and listings. The 3270-display default colors are set for a particular database.

66-32

Forms for 3270-Display Defining Colors for 3270-Display Forms

To set the colors for a particular database:

1 As the administrator, choose Configuration tab > Tuning > Database Standards. The Database Standards form is displayed. 2 Click the 3270 button. The Terminal-3270 form is displayed:

Use this form to define parameters that affect 3270 terminals. Changes in these parameters take effect only after the database has been reopened.

66-33

66

Forms for 3270-Display Defining Colors for 3270-Display Forms

3 Click the Colors button. The Color Standards form is displayed:

4 Use this form to define colors used in 3270-display forms. The following colors can be defined: Blue Green Pink Red Turquoise Yellow White Each color can be defined with one of the following properties: Normal Blink Reverse Underscore The colors of the form frame, error messages, and listings may be overridden via this form only. You can also override the global default colors for blocks, menus, and fields on the form by specifying your installation global default colors for the database.
66-34

Forms for 3270-Display Defining Colors for 3270-Display Forms

Changes made to the colors take effect at the next session.

In TSO, the session should be restarted. In CICS or IMS, the color defaults are taken from the CT database for all databases used. If the defaults are changed, Business Integrity Server should be closed (CLOSETP) and reopened.

The supplied global defaults, which are used if no other value is specified, are: Field Name in Form title frame command word command answer status err stat listing error msg err occur selection opt ans opt no menu text menu fld comm name value trail text intxt Field Name in Operation title color frame color comm. word color user comm. color status color error status clr listing color error msg color err occur selection color option ans clr option no. color option text clr option field clr common fld color field name color value color trailer color text color intensified text Color bluenormal greennormal greennormal whitenormal turquoisenormal rednormal bluenormal rednormal -reverse turquoisenormal whitenormal bluenormal turquoisenormal whitenormal turquoisenormal turquoisenormal whitenormal turquoisenormal turquoisenormal bluenormal

66-35

66

Forms for 3270-Display Creating a Menu for 3270-Display

66.18 Creating a Menu for 3270-Display

To define a menu:

1 From the Presentation tab, right-click the Forms node and choose the New Menu Form option. The Menu form is displayed:

2 Enter the number and name for the menu in the Form No. and Name fields. The name can be up to 16 characters, consisting of letters, digits, blanks and any of these special characters: - _ ' " . and #. 3 Choose no template (blank value) in the Template field. 4 Assign any relevant options. Note that the GUI Menu, Window, and Privacy subgroupboxes are not supported for 3270-display forms.

66-36

Forms for 3270-Display Creating a Menu for 3270-Display

5 Enter the menu options. Each menu option consists of the following parts: No: The number of the menu option. This determines the order in which they are displayed. You can overwrite these numbers (e.g. if you want increments of ten) by typing the number you want over the displayed number. Called Form: The number of the form to be called when the menu option is chosen. Displayed Text: A string that explains the menu option. If no displayed text is defined for a menu option, then the name of the form or the BLP command will be displayed in its place. BLP Command: chosen. The command to be issued when the menu option is

6 Click Apply to create the new menu. 7 Unassign the GUI option. 8 Test the menu display via a 3270 terminal or 3270 emulation.

66-37

66

Forms for 3270-Display Creating a Menu for 3270-Display

66-38

Chapter 67 Customizing Form Frames

A form frame consists of the first few lines in the form (the frame header) and the last few lines in the form (the frame footer). eMerge comes with a default form frame defined in the Pure. It consists of two lines in the frame header and up to four lines in the frame footer (depending on how many form-dependent actions are defined for the form) as in the following example of a form with the default eMerge form frame:
SAPIENS - OPERATION COMMAND => FIELD DETAILS-FIELDS IN BLOCK (000616-000651)

****

FORM BODY

****

==

INPUT

==..................... S D4 $SYS

02/02/2003 11-FLDETAIL

14:30:40

1-HELP 2-SELECT 3-QUIT 4-NEW 5-CONT 7-BACK 8-FORW

You can design your own form frame to be used in all forms displayed in your application, for 3270-display forms. Any application for which you do not design your own frames has the default format. When you design a form frame, you specify which elements appear in the frame, and their locationswhether in the frame header or the frame footer, and in which line and field. You can define several different frames in a database and then use different ones for different applications.

67-1

67

Customizing Form Frames Frame Elements

A form frame definition is actually stored as a form definition, so if you receive any error messages while using form frames, the messages may refer to forms.

67.1 Frame Elements

A form frame is made up of various frame elements. The following figure shows the names of the frame elements used in the default form frame. Each element name is shown in its position in the default frame.
<SAPT> - <FRTY> <COMT> => <COMA> <FRTI> <FRID>

****

FORM BODY

****

== <STAT> ==..........<SCEN>....<BATR>..

<MODE>

<DBID>

<USER>

<DATE>

<TIME>

When you design a customized form frame, you can use the elements that make up the default eMerge frame, and additional elements that do not appear in the default frame.

APPL

The command line can be disabled. See "Disabling the Command Line" on page 67-10.

Following is a list of all of the elements that can appear in a user-defined frame.
Note the length and if the LENGTH OVERR. option is assigned is noted for each element. See "LENGTH IN FRAME" on page 67-9.
APPLICATION TITLE NAME

Title of the application, as defined in the APPLICATION field in the WORKING PROFILE (210015) form. Length 78; LENGTH OVERR. option assigned.

67-2

Customizing Form Frames Frame Elements

BATR

BATCH-RELEASE NO

The number of the batch or release, whichever is applicable. You can use this element for other purposes, by assigning a constant string to it. Length 6. CONSTANT VALUE option assigned. A constant string. Use CNST when you want a particular string to appear on every form that uses this frame. Length 78; LENGTH OVERR. option assigned. CONSTANT VALUE option assigned.

CNST

CONSTANT VALUE

COMA COMC

COMMAND AREA

The space where the user can enter BLP commands. Length 60; LENGTH OVERR. option assigned.

CUA COMMAND TITL The string "COMMAND =>" that shows the user where to enter BLP commands. This is only applicable if you are working with IBMs CUA (Common User Architecture) standard. Length 12 COMMAND TITLE

COMT

The string "COMMAND =>" that shows the user where to enter BLP commands. If you would like to use some other string for this prompt (other than COMT or COMC), define a CNST element with the desired value. Length 10

DATE

The current date format, displayed as specified (AmericanDate, ReversedDate or MixedDate) via the Database Standards form. The date format in the DEFAULT FRAME (11000) is DD-MM-YY. If you use the FRAME LONG DATE (11001) you can specify the Date System Format as DD-MM-YY, DD-MM-YYYY, or DD-MMM-YYYY. Length 8; LENGTH OVERR. option assigned.
CURRENT DATE DATABASE ID The two-letter database identification associated with the database you are using in this session. Length 2 FORM ID FRNO

DBID FRID

The form identification is a combination of the frame elements (form number) and TRNO (the number of the operation or program or query, depending on what the form displays), with a dash joining them and parentheses surrounding them, i.e. FRID = (FRNO-TRNO).

If more than one block is displayed by the form, then only the form number is displayed by FRID. Length 17 FRNM
FORM NAME

The name of the form, which is one of the following:

If the Title option is assigned for the form, the value of the FORM NAME field as specified in the Form Definition form. If the Title option is not assigned for the form, the name of the most recent calling form for which the Title option was assigned. Length 16

67-3

67

Customizing Form Frames Frame Elements

FRNO FRTI

FORM NO. The number of the form which is the value of the FORM NO. field as specified in the Form Definition form. Length 6 FORM TITLE The title of the form. FRTI is a combination of the frame elements FRNM and TRNM, with a dash joining them. It consists of one of the following:

If the Title option is assigned and the form displays one block: the name of the form followed by a dash followed by the name of the operation. If the name of the form is identical to the name of the operation, then one title is displayed. If the Title option is assigned and the form displays more than one block: the name of the form. If the Title option is not assigned: the name of the most recent calling form for which the TITLE option was set. Length 36 FRTY
FORM TYPE The type of the form being displayed. This is determined by the system during the application flow. The possible values are: MENU, OPERATIONS, LIST, HELP, PROG-INPUT, PROG-OUTPUT, QUERY-INPUT, QUERYOUTPUT, CHECKSETS, VALUES.

Length 14

MODE

UPDATE MODE The mode under which updating is performed, either by single operations or using operation groups. The possible values are: S (single mode) or G (group mode). Length 1 ALL PFS

PFS

All of the function keys currently active, including both the system and the user-defined private function keys. When this element is used in a frame, the PFSY and PFUS elements cannot be used in the same frame.

When separate function key elements (PFSY and PFUS) are specified in the frame definition, the BLP command CONCATPF does not work in that frame. (The CONCATPF command, issued during a user session, causes the user defined actions to continue on the same line as the system actions, for that session, rather than starting on a new line.) The number of action lines can be decreased by issuing an appropriate command (e.g. SET PF SYS NODISPLAY, PF NN NODISPLAY, CONCATPF), or assigning an appropriate option; e.g. NoDisplayName option via the Form/Menu Actions form or ConcatAction option via the Form Definition form. Length 80 PFSY PFUS
67-4 SYSTEM PFS USER PFS

The system actions currently active. Length 80

The user-defined actions currently defined. Length 80

Customizing Form Frames Frame Elements

SAPT SCEN

SAPIENS TITLE The text string "SAPIENS". If you want some other string to appear, use a CNST element instead of the SAPT element. Length 8 SCENARIO STATUS The status of the scenario (the screen capturing facility) if applicable. The possible values are: PLAYING, RECORDING. Length 18. CONSTANT VALUE option assigned. SCROLL COUNTER The occurrence counter in a scroll frame. It appears as: N OF M where M is the total number of lines of output to be displayed and N is the number of the output line currently displayed at the top of the form. Length 17 SCREEN STATUS

SCRC

STAT

The status of the form. The possible values are: LISTING, Length 10

WARNING, ERROR, INPUT, MODIFY, MENU, TRUNCATED, REJECTED, TOP, BOTTOM, CONTINUED, INVALID, NOT FOUND.

TERM TIME TRNM TRNO USER

TERMINAL ID CURRENT TIME TRANS NAME

The identity of the terminal. For CICS only. Length 8 The current time in the format hh:mm:ss. Length 8 The name of the operation. Length 16

TRANS NO. The number of the operation (or query or program, depending on what the particular form displays). Length 6 USER ID

The userID under which the user is currently working. Length

8 The elements are listed in the LIST OF ELEMENT (209001) form:

67-5

67

Customizing Form Frames Using a Custom Form Frame

Each element is shown with its lengththe number of characters it takes up in the form. In addition, some of the elements have one or more of the following options:
OVRLENG SCRLONLY NOTONSCR

The length of the element can be overridden. The element can appear only in a scroll form. The element cannot appear in a scroll form.

CONSTANT The element can have a constant value assigned to it. The values of most of the elements are taken from the system, or have been defined in other forms. Elements with the CONSTANT option can be explicitly assigned a value. UNIQUE

The element can appear only once in a form.

67.2 Using a Custom Form Frame

To use a custom frame:

1 As the administrator, design the form frame via the FRAME DEFINITION form. See "Designing the Form Frame" below 2 As the administrator, assign the frame to the application by assigning it to the appropriate World. See "Assigning the Frame to the Application" on page 67-9.

67.3 Designing the Form Frame

To design a form frame:

1 As administrator, enter the following in the Open Form box in Development Workbench:
Form 696

The FRAME DEFINITION form is displayed:

67-6

Customizing Form Frames Designing the Form Frame

The default form frame is the QUERY SLCT (11000) frame. If you want to be able to display dates that show the century as well as the year, another default frame is available: the FRAME LONG DATE (11001) frame. 2 Use the following information to fill in the form. Note that there are two sets of elements: those in the HEAD FRAME block and those in the FOOT FRAME block. There more elements than displayed in the above figure. Additional elements can be retrieved by positioning the insertion point on the FOOT FRAME block and clicking PF8 (FORWARD). FRAME NO. The number that uniquely identifies the frame. The allowed frame number range is the same as the allowed form number range. The frames supplied in the Pure are in the range 1130011999. These are example frames only and should not be directly assigned to applications. FRAME NAME The name that identifies the frame. The name can be up to 16 characters long. It can include letters, digits, blanks, and any of the following special characters: $ - _ " . / #. If the frame name is unique, then you can use the frame name in place of the frame number to identify the frame. LIN The line in which the element is displayed.

You can have any number of frame footer lines, as long as they all fit on your form. You number the lines in the LIN field, starting with 1. The position of the first line in the frame footer is determined by the number
67-7

67

Customizing Form Frames Designing the Form Frame

of footer lines you define, and the number of lines on the whole form. If, for example, your frame footer contains three lines, and your form consists of 24 lines altogether, the first line in the frame footer is on line 22 in the form. Any change in the number of frame lines is automatically reflected in the number of lines available for the form body. When the ELEMENT CODE refers to the PF keys (i.e. PFS, PFSY, PFUS), the line number that you specify only designates the display sequence. The number of lines used for the display of the PF keys varies with the number of active PF keys in the current form and with the commands and options currently active (e.g. Nodisplay, ConcatAction). ELEMENT CODE The code that identifies the element. The details of a code in this field can be obtained by zooming from this field. ELEMENT NAME The element name is filled in automatically when you specify an element code. COL The starting display position for the element. You must insure that the space left between the specified column and the end of the line is sufficient to contain the element, since no overlapping is allowed. As a default, if no column is specified for an element, the element is displayed after the preceding element in the line, with one space between them. CHKS These frame options can be applied to change the appearance of an element:
CENTER 0040

The element value is centered within the defined length.

CONCAT 0004 The element value is displayed concatenated with the preceding element in the line and the element inherits the screen attribute of the preceding element (e.g. color, intensification, blinking mode, etc.). INTENSIFY 8000 NOCOMLIN 4000

The element is displayed intensified.

No elements are displayed in the command line. Use this option in conjunction with the NoCommand option (assigned via the Form Definition form) so that no elements are displayed on the command line. If only the NoCommand option is assigned, some elements are displayed, but if nocomlin is also assigned, then no elements are displayed.

Assign the NOCOMLIN attribute via the CHKS field for the COMA element. This causes automatic assignment of the NOCOMLIN option to all the elements in the Command Line.
67-8

Customizing Form Frames Assigning the Frame to the Application

RIGHTJST 0080

The element value is right-justified; i.e. aligned with the last character position.

For right-to-left languages, the meaning of RIGHTJST and the default display option are the opposite of what they are for left-to-right languages.
ZEROSUP 0400

Leading zeroes of the element value are not displayed.

COLOR Specifies the color and display mode (normal, blinking, reverse video, or underscore) for the element. LENGTH IN FRAME The actual maximum length that you wish to specify for the element being defined. It must be shorter than the ELEMENT LENGTH displayed in the LIST OF ELEMENT (209001) form. It can only be specified for elements assigned the LENGTH OVERR. option (length can be overridden). See "Frame Elements" on page 67-2 for a list of the frame elements. The length and if the LENGTH OVERR. option is assigned is noted for each element. CONST. VALUE Indicates (via an X in the field) that a constant value has been defined for the element. This field is relevant only for elements specified with the CNST (CONSTANT VALUE) ELEMENT CODE or with any other ELEMENT CODE that has the CONSTANT VALUE option assigned (i.e. can have a constant value assigned to it). See "Frame Elements" on page 67-2 for the frame elements assigned the CONSTANT VALUE option. For a CNST (CONSTANT VALUE) element or any other ELEMENT CODE that has the CONSTANT option (can have a constant value assigned to it), you can specify a constant string to be displayed where this element appears in the frame. The constant string can be displayed or defined via the ELEMENT CONSTANT (697) form for the HEAD FRAME, or via the ELEMENT CONSTANT (689) form for the FOOT FRAME, by clicking the CONSTANT button with the insertion point on the relevant element.

67.4 Assigning the Frame to the Application

Once you have defined your custom form frame, assign it to an application by defining the application as a world. 1 As administrator, enter the following in the Open Form box in Development Workbench:
Form 210015

The WORKING PROFILE form is displayed.

67-9

67

Customizing Form Frames Disabling the Command Line

2 Access the world definition that is needed. 3 Place the number of the custom frame in the FRAME field. The frame assigned here must already have been defined. 4 Place the number of the application's top form in the TOP FORM field. Thus, when you assign a frame to an application, the frame is assigned to the world's TOP FORM. A customized frame cannot be used for an application that has no TOP
FORM. FORM

You can assign only one FRAME to a TOP FORM. If you use the same TOP in different applications you cannot assign another FRAME to that TOP FORM.

5 Specify the application title in the APPLICATION NAME field. This may differ from the world name. If you use the APPL (application name) element in the form frame, the title displayed is taken from the APPLICATION NAME field specified here. If an APPLICATION NAME is not specified and the APPL element is defined in a frame definition, then the world name is used as the default.

67.5 Disabling the Command Line

Assign the NoCommand option via the Form Definition form (see Step 4 on page 66-9) so that the command line is not displayed on the form (i.e. the user cannot issue commands which require the command line), and an extra line is available for form content.
67-10

Customizing Form Frames Disabling the Command Line

When you customize your form with a frame, some elements of the command line (e.g. constants, or the COMC or COMT elements) may be displayed, even after assigning the NoCommand option. Assign the NOCOMLIN option (in addition the NoCommand option) to prevent display of all elements in the command line. See "nocomlin 4000" on page 67-8.

67-11

67

Customizing Form Frames Disabling the Command Line

67-12

Chapter 68 Documentation and Help Text for 3270Display Applications

Documentation text can be entered for knowledgebase objects. The text is entered and viewed by the application developer, to provide a description of the object, and any other information. Documentation provided for fields, blocks, forms and menu options can be accessed as help text by the end user.

68.1 Documenting Knowledgebase Objects

These types of knowledgebase objects have documentation forms that can be accessed from their definition form by pressing the DOCUMENT PF key: Action Block Class Composite Concept Constructor Field Field in Block Field in Class Field in Operation Field Value Form/Menu Job Menu Option Operation Program Query Rule Ruleset Value

For most knowledgebase objects, there are also documentation forms for entering documentation text for a second language and for additional languages. For each type of object, the documentation form is accessed from the definition form by clicking the Document button.

68-1

68

Documentation and Help Text for 3270-Display Applications Help for Fields, Blocks, Forms and Menu Options

68.2 Help for Fields, Blocks, Forms and Menu Options

Documentation provided for fields, blocks, forms, and menu options can be accessed by the end user by clicking PF1 (HELP):

If the cursor is on a field value, the field help is displayed. If the cursor is within a block but not on a field, the block help is displayed. If the cursor is within the form but not within a block, the form help is displayed. If the cursor is on a menu option, the menu option help is displayed.

This means that care must be taken to ensure that field, block, form, and menu option documentation is correct and attractive. It should not contain any information that you do not want the end user to view.

68.3 End-User Help for Fields, Blocks, Forms and Menu Options
Documentation provided for fields can be accessed by the end user by clicking the Help button on the toolbar when the insertion point is on a particular field. This means that care must be taken to ensure that field documentation is correct and attractive. It should not contain any information that you do not want the end user to view.

Defining Help Text

Defining help text is similar for all knowledgebase objects. Defining help for fields is described here as an example for all knowledgebase objects.

To define help for a field:

1 In the model, select an object that has fields and click the Fields button to access the Concept form. 2 With the insertion point on the definition of the field for which you want to provide documentation, click FieldDef to access the Field Definition form.

68-2

Documentation and Help Text for 3270-Display Applications End-User Help for Fields, Blocks, Forms and Menu Options

3 Click the Document button to access the Field Documentation form.

4 Enter documentation text. To advance to a new line, press <Shift>+<Enter>. 5 If necessary, click the SecondLang or Language button to enter documentation in another language.

Skipping to a New Line

By default, the help text is filled. It is concatenated together and split into full lines of text. In order to cause text to be placed on a new line, place the .br command by itself on a line.

Displaying a Blank Line

In order to cause a blank line to be output, place the .sp command by itself on a line.

Turning Formatting On and Off

Use the .nf and .fo commands to suspend formatting for text lines. .nf .fo Formatting is not performed on text lines following this command. They are output as entered, with no fill. Turns formatting back on.

68-3

68

Documentation and Help Text for 3270-Display Applications End-User Help for Fields, Blocks, Forms and Menu Options

Example without .nf

This form is used to enter student data for .sp under graduates continuing education golden age program This form is used to enter student data for under graduates continuing education golden age program

Resulting Output without .nf

Example with .nf

This form is used to enter student data for .sp .nf under graduates continuing education golden age program .fo This form is used to enter student data for under graduates continuing education golden age program

Resulting Output with .nf

Designating Text Lines for DETAIL ON Mode Only

If the form has fields that are displayed only if DETAIL ON has been issued, you can use the .detail on and .detail off commands to set off text to be displayed only in DETAIL ON mode. .detail on .detail off Lines of text following this command are only displayed when in detail mode. Lines of text following this command are always displayed.

Including Documentation Text From Another Field

To include documentation text that was defined for a different field, at the end of the help text for the current field, use this command, where <field-no> is the field number of a different field:
.include <field-no>
68-4

Documentation and Help Text for 3270-Display Applications End-User Help for Fields, Blocks, Forms and Menu Options

Use this command for field documentation only. This command must be the last line in the text.

Displaying the Fields Possible Values in its Help Text

For a field that has possible values defined for it, you can include the list of possible values in the help text. Use this command with field documentation only.
.include values

Use this command for field documentation only. This command must be the last line in the text.

Fields Containing a Minus Sign as Data

If a field contains as data, a minus sign (-) and no other characters, the help text supplied is not displayed to the end user. If the field has possible values defined for it, the fields possible values are displayed.

Example of Help Text Formatting

The following documentation is provided for a field that has possible values defined.

68-5

68

Documentation and Help Text for 3270-Display Applications End-User Help for Fields, Blocks, Forms and Menu Options

SAPIENS - OPERATIONS COMMAND => FIELD NO. C _4203 SEQ. NO. C C C C C C _ _ _ _ __1 __2 __3 __4 __5 __6 _10 _20 _30 _40 .sp FIELD NAME STUDENT AGE

FIELD DOCUMENT INPUT FIELD SCL NAME ________________ DOCUMENT TEXT LENGTH __4 DATA TYPE B

(000160)

The age of student applying for tuition assistance. .sp You must enter a number within these allowed ranges: .sp .include values ___________________________________________________ ___________________________________________________ ___________________________________________________ ___________________________________________________ Use 'MORE' for value document.

== INPUT 1-HELP 9-EDIT

==.................. S 2-SELECT 10-VALUE 3-QUIT 11-SUBJECT 18-GUI 4-NEW

UO

$SYS 5-CONT

02/02/2003 6-MORE 7-BACK 13-SUBFIELD 20-ENEXCMND

14:44:40 8-FORW 24-ZOOM 14-EDITRULE 22-MENU

12-SECLANG 19-FIELDS

16-CLSRULE

17-PRE/SUF

When the end user presses PF-1 (HELP) the following help is displayed:
*** HELP FOR FIELD 4203 - STUDENT AGE : DATA TYPE=B, LEN=004 *** The age of student applying for tuition assistance. You must enter a number within these allowed ranges: * 15 - 25 - UNDER GRADUATE * 30 - CONTINUING ED. 30'S * 40 - CONTINUING ED. 40'S * 50 - CONTINUING ED. 50'S * 120 - GOLDEN AGERS MSG2703 *** END OF DATA - PRESS "ENTER" TO CONTINUE ***

68-6

Appendix

Appendix a To i.way from Sapiens Workstation

a.1

Moving to an i.way Display

Applications that were developed and accessed via Sapiens Workstation and now will be accessed via i.way have to be reviewed and possibly modified. That is, moving to an i.way-based (web-based) display requires changes to existing and new forms. Existing forms may need to be modified to take advantage of the many benefits of i.way-based display. New forms (both data forms and menus) should be defined that take advantage of the i.way-based display. The procedure for developing forms accessed via i.way is not the same as the one for forms accessed via Sapiens Workstation. The new procedure lets you take advantage of the i.way-based features. This chapter describes how to modify an existing set of application formsforms that were developed and accessed via Sapiens Workstation and now will be accessed via i.way. The chapter contains the modifying procedure for Sapiens Workstation forms and a set of considerations for Sapiens Workstation forms.

a.2

Modifying Sapiens Workstation Forms

This section gives a set of steps to be followed for forms that were developed and accessed via Sapiens Workstation. The steps include:

BackgroundUnder what conditions the step should be done. What to doExactly what should be done. If the step includes a query, the query number and needed parameters are given. Some of the queries are for information only (e.g. identify the needed forms) and some queries actually do an update (e.g. assign an option to a form).
Queries 1654, 1655, 1656, 1657, 1658, 1662, 1663, 1664, 1669, 1682 and 2650 2662 create files of operations with five digits.

ResultDescribes the modifications that were done and what further actions may need to be done for this step.

a-1

To i.way from Sapiens Workstation Modifying Sapiens Workstation Forms

All forms that were modified via the given queries must be reloaded by clearing the local database. See eMerge Client Installation & Administration Guide.

The procedure must be followed in the order given. Background All the forms in the application that have GUI definitions need to be identified. Forms that have GUI definitions should have the Width field defined for the form. However, there are forms which have GUI definitions, but do not have the Width defined. These must be identified and the Width defined for the form. What to do Parameters From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Result Finds all forms that have the X Position, Y Position or the Bkg Color defined. Using the form list, display each form via Form Editor and define the Width for the form by changing the size of the form (a slight change is sufficient) and saving the change. 2 Background Images used in forms and actions can be either .jpg or .png. After the conversion of all the images from .bmp to either .jpg or .png (outside eMerge), the name of the images files must be changed from *.bmp to *.jpg or *.png. What to do in actions). Parameters File ExtThe file extension of the image files: jpg or png. From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Result Finds the image files in all form (Query 1655) and action (Query 1656) definitions and changes the file extensions to .jpg or .png, depending on what is requested. 3 Background Jut In lines, and Jut In and Jut Out frames for rectangles in Sapiens Workstation were displayed as gray. In i.way the Jut In lines, and Jut In and Jut Out frames for rectangles appear to be green. The Jut Run Query 1655 (for images in forms) and 1656 (for images Run Query 1681.

a-2

To i.way from Sapiens Workstation Modifying Sapiens Workstation Forms

In lines, and Jut In and Jut Out frames for rectangles must be identified and changed to gray. In addition, the color of Flat rectangle frames were stored in a different field in Sapiens Workstation (i.e. Color) than in i.way (i.e. Frame Color). The color must be moved to the correct field. What to do Parameters From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Result Finds the forms that contain Jut In lines and Jut In and Jut Out rectangle frames and changes the color of the Jut In lines, and Jut In and Jut Out rectangle frames to gray by storing the gray color in the Frame Color field. Finds the forms that contain Flat rectangle frames and moves the color of the Flat frame from the Color field to the Frame Color field. 4 Background It wasnt possible to define a color for buttons in Sapiens Workstation. All buttons were displayed as gray. These buttons are transparent via i.way. These must be identified and set to gray. What to do Parameters From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Result 5 Finds the forms that contain buttons and sets the color to gray. Run Query 1661. Run Query 1657.

Background A name for an action was required in Sapiens Workstation (it is not required in i.way). In cases where the name was not needed or wanted on the form (e.g. an image was defined for the button), the name was hidden in various ways. These must be identified as they may cause problems in i.way. A. What to do Parameters From FormThe number of the first form in the range of forms that must be checked. Run Query 1667.

a-3

To i.way from Sapiens Workstation Modifying Sapiens Workstation Forms

To FormThe number of the last form in the range of forms that must be checked. Result Finds the forms that contain actions with images. The list is sorted according to the image file. For each image file, the forms (that contain the image) and the actions in the form (that use the image) are listed. Review the list to decide which actions that have an image defined should not have the name displayed. For those, run Query 1668. B. What to do Parameters From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Image FileThe name of the image file that should not have the name displayed on the action. Result Assigns the NoDisplayName option to all the actions that contain the image entered as a parameter in the query. 6 Background If changes were made to the default fonts defined in the [Font] section in the sws.ini file, font information must be entered for the default formatting for:

Run Query 1668.

field names field values and trailers fields assigned the Common option fields assigned the Protected option actions top and bottom text Run Queries 1658.

A. What to do Parameters

FontIDThe number that identifies the font in the [Font] section of the sws.ini file. Font HeightThe height of the font in pixels for field names, field values, fields assigned the Common option, fields assigned the Protected option, and trailers. Font ChecksetThe options that determine bold and/or italic for field names, field values, fields assigned the Common option, fields
a-4

To i.way from Sapiens Workstation Modifying Sapiens Workstation Forms

assigned the Protected option, and trailers: 8000 for bold, 4000 for italic. Font HeightThe height of the font in pixels for the text on actions. Font ChecksetThe options that determine bold and/or italic for the text on actions: 8000 for bold, 4000 for italic. Font HeightThe height of the font in pixels for top and bottom text. Font ChecksetThe options that determine bold and/or italic for the top and bottom text: 8000 for bold, 4000 for italic. From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Result Inserts the default formatting for all forms according to the parameters entered in the query. For those form objects that have font options (i.e. height, bold, italic), but no Font ID, run Queries 1662, 1663, 1664 and 1682. B. What to do Run Queries 1662 (for field names, field values and trailers), 1663 (for top text), 1664 (for bottom text) and 1682 (for actions). Parameters FontIDThe number that identifies the font in the [Font] section of the sws.ini file. From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Result Inserts the FontID for those form objects that have font options (i.e. height, bold, italic), but no Font ID. 7 Background In Sapiens Workstation, the default color of all blocks was gray. In i.way, all blocks are transparent. Blocks that were defined with a color other than gray in Sapiens Workstation must be identified and the color removed. A. What to do Parameters Run Query 1678.

a-5

To i.way from Sapiens Workstation Modifying Sapiens Workstation Forms

From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Result gray. Finds the forms that contain blocks with a color other than Run Query 1679.

B. What to do Parameters

From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Result Removes the color from the block definitions. If a color (other than the background color of the form) is wanted, a rectangle of the chosen color should be placed under the block. 8 Background In Sapiens Workstation, forms may contain inherited actions. These must be identified. Inherited actions are not recommended for use in i.way forms. What to do Parameters From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Result Finds the forms that contain inherited actions. Assign the Local option to the action. This avoids inheritance. 9 Background The Scrollbar option is not supported in i.way. Blocks that have the Scrollbar option assigned should be identified and have the Previous and Next actions defined for the block. In addition, non-fixed occurrences (i.e. the Occurrences field for the block in the form is defined as less than zero) can be problematic if any form objects are placed under the block in the form. A. What to do Parameters Run Query 1653. Run Query 1680.

a-6

To i.way from Sapiens Workstation Modifying Sapiens Workstation Forms

From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Result Finds the forms that contain blocks assigned the Scrollbar option and forms that contain blocks with the Occurrences field for the block in the form defined as less than zero. B. What to do For multi-occurrence blocks assigned the Scrollbar option, run Query 1654 twice: once for Previous and once for Next. Parameters From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. PF No.The number of the action. WidthThe width in pixels of the action. HeightThe height in pixels of the action. Button CksThe option that determines how the action is displayed: 0040 for HyperImage. BLP CommandThe command called by the action: Previous or Next. Image FileThe file of the image to be placed on the new action. File ExtThe file extension of the image to be placed on the new action: jpg or png. Client Block No.The number of the block in the range of forms that needs the Previous or Next button. Result Inserts the Previous or Next button in the block according to the parameters entered in the query. C. What to do For blocks with the Occurrences field for the block in the form defined as less than zero, define a fixed occurrence (i.e. greater than or equal to zero). 10 Background It was possible in Sapiens Workstation to hide some form objects by making the forms smaller; i.e. some of the form objects were hidden in the "undisplayed" part of the form. In i.way, such forms get scrollbars, so no form objects can be hidden within the "undisplayed" part of the form. These must be identified.
a-7

To i.way from Sapiens Workstation Modifying Sapiens Workstation Forms

What to do Hide form objects in other ways than making the forms smaller. For example, assign Ignore and KeepValue for a field. 11 Background In i.way, the DETAIL command is not supported. The forms that use the DETAIL command must be identified and redesigned. What to do Via the Tools tab, right-click Form Information and choose BLP Commands in Forms. The BLP Commands Information (100039) form is displayed. Search for the DETAIL command for all three options (i.e. Private Commands, Menu Options and Entry/Exit Commands). Result 12 Finds the forms that use the DETAIL command.

Background In i.way, DDE programs are not supported (OLE is supported). The DDE programs must be identified. What to do Result Run Query 1660.

Finds the DDE programs.

13

Background In Sapiens Workstation, a menu assigned the GUI option but not assigned the ButtonMenu option was displayed as a listbox. This is not supported in i.way. Menus assigned the GUI option, but not assigned the ButtonMenu option, must be identified and redesigned. What to do Parameters From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Result Finds the menus assigned the GUI option but not assigned the ButtonMenu option. Run Query 1650.

14

Background In i.way, the PRLLFORM option for a form (i.e. a form with more than one block, such that each block calls another form; that is, more than one form is displayed at the same time) is not supported. The forms that use the PRLLFORM option must be identified and redesigned. What to do Parameters From FormThe number of the first form in the range of forms that must be checked. Run Query 1652.

a-8

To i.way from Sapiens Workstation Modifying Sapiens Workstation Forms

To FormThe number of the last form in the range of forms that must be checked. Result 15 Finds the forms assigned the PRLLFORM option.

Background If a top, bottom, prefix or suffix text was placed on the frame of a rectangle in Sapiens Workstation, the rectangle frame didnt show under the text. It was as if an opaque rectangle was under the text, but above the frame rectangle. In i.way, the frame rectangle shows up since the background of a text is transparent. What to do the text. Via Form Editor, a background color should be chosen for

16

Background Forms in i.way are displayed maximized and positioned at the top-left corner. If the form size isnt big enough, the maximized form is displayed on the default background. What to do Parameters WidthThe width in pixels of the maximized form. HeightThe height in pixels of the maximized form. GUI Object NOAn available number used to identify an image, rectangle or line for a form. Ninety-nine (99) is usually OK. From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Result Sets the X Position and Y Position of the form to zero, increases the size of the form (according to the parameters entered in the query) and inserts a rectangle that is the size of the original form. Run Query 1669.

17

Background If the forms developed in Sapiens Workstation were developed with a different resolution than the resolution used in Development Workbench, the form objects must all have their size increased accordingly. What to do Parameters Relative IncreaseThe relative amount the form objects must be increased. The relative increase is: <new resolution>/<old resolution>
a-9

Run Queries 26502662 for the relevant form objects.

To i.way from Sapiens Workstation Considerations for Sapiens Workstation Forms

Example: If the Sapiens Workstation forms were developed with 800 X 600 and the work in Development Workbench is with 1024 X 768, the relative increase is: 1024/800 = 768/600 = 1.28 From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Result The following table shows the query number and to which form objects it is relevant: Query Number 2650 2651 2652 2653 2654 2655 2656 2657 2658 2659 2660 2661 2662 Result Increases the font size of field names, field values and trailers. Increases the font size of top text. Increases the font size of bottom text. Increases the font size of action text. For i.station. Increases the size of the form. For i.way, run Query 1669. See 16 on page 9. Increases the size of images, lines and rectangles. Increases the relative size of each button. Shrinkwraps top text. Shrinkwraps bottom text. Shrinkwraps prefix text. Shrinkwraps suffix text. Shrinkwraps field names, field values and trailers. Increases the size of button images and centers button text.

a.3

Considerations for Sapiens Workstation Forms

The following considerations should be made when moving from Sapiens Workstation to i.way: 1 Background Search for all forms with GUI definitions.

a-10

To i.way from Sapiens Workstation Considerations for Sapiens Workstation Forms

What to do Via the Tools tab, right-click Form Information and choose Forms with GUI Parameters. Or Run Query 1665. Parameters From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Result 2 The output can be used as a checklist. All flows should be checked. For big applications, use the List Flow utility with NOSCRN All calls for forms via BLP commands should be checked.

Background What to do option. Background

What to do Via the Tools tab, right-click Form Information and choose BLP Commands in Forms. The BLP Commands Information (100039) form is displayed. Search for the FORM command for all three options (i.e. Private Commands, Menu Options and Entry/Exit Commands). Background In Sapiens Workstation, called forms were displayed so that blocks of the calling form act as a header for the called form; i.e. the called form is smaller and moved such that the calling form is visible. When accessing an eMerge application via i.way using a web browser (which is an SDI environment), all forms are displayed maximized, so the calling form is not visible at all. What to do 3 Consider adding the calling blocks to the called form.

Background After dealing with all font issues, it is recommended using the ShrinkWrap option on all field names and other texts. In some forms, field names, field values and other form objects need to be aligned. What to do Shrinkwrap field names and other texts by right-clicking the form object (or a set of form objects) and choosing Shrinkwrap. Align form objects by selecting the set of form objects (needing alignment), right-clicking, and choosing Align. Alignment can be done horizontally (left/right) or vertically (top/bottom).

Consider defining a new tab-order for forms that have fields that are not shown in the same order as in the operation.
a-11

To i.way from Sapiens Workstation Considerations for Sapiens Workstation Forms

Consider displaying field names in titlecase. What to do Parameters From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Result All field names are changed to titlecase. However, check the results for there may be words in the field names that should not be titlecase; e.g. acronyms. Run Query 1659.

Consider adding rectangles for form blocks. What to do Parameters From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Result Deletes, for each application form, the GUI definitions of each form block and defines a rectangle with the same GUI definitions as the form block. Run Query 1615.

7 8 9

Consider adding tooltips for actions. Consider adding titles for forms in place of the names given when the form is first defined. Background In Sapiens Workstation, all images on buttons were displayed as transparent, whether the image was transparent or not. In i.way, any image that is not transparent is displayed as "not transparent". What to do Assign the HyperImage option to the image or convert the image to a transparent image.

10

Background In Sapiens Workstation, a form could contain both blocks and menu options. This is not recommended in i.way. Thus, in i.way, a form that contains both blocks and menu options should be split into two forms: one with blocks and an action that calls a menu and two a menu containing the relevant menu options. What to do Run Query 1677.

a-12

To i.way from Sapiens Workstation Considerations for Sapiens Workstation Forms

Parameters From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Result Finds the forms that contain both blocks and menu options. Using the output list, make a copy of each of the relevant forms (forms that contains both blocks and menu options). The copy is used for the menu; the original form is used for the blocks and the action that calls the menu.

In the original form: delete the menu options define an action that calls the menu In the copy of the form: delete all the blocks delete all unnecessary actions and definitions (e.g. error overrides) via Form Editor, reset the form to eliminate all GUI definitions via Form Editor, define a template for a menu and add any needed GUI definitions

11

In i.way, the PRLLFORM option for a form is not supported (see 14 on page 8). What to do Parameters From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Finds the forms assigned the PRLLFORM option. For each form, the following procedure gives the effect of the PRLLFORM option by opening a flow of forms that open at the same time. Result
PRLLFORM

Run Query 1652.

The diagram shows how the calling form called the original PRLLFORM form (each block calls another form), as opposed to the new procedure which is a flow of forms that are open at the same time.

a-13

To i.way from Sapiens Workstation Considerations for Sapiens Workstation Forms

1 Define the calling form (i.e. the form that called the form assigned the PRLLFORM option) to call the first form in the PRLLFORM form. 2 For each form in the PRLLFORM formexcept the last form in the PRLLFORM form:

Define a logical action that calls the next form of the PRLLFORM form. Define an OnLoad event that activates the logical action.

a-14

To i.way from Sapiens Workstation Differences between i.way and Sapiens Workstation

3 Note the following:

If a form called by the PRLLFORM form executes a query with an output form, the logical action and the OnLoad event should be defined for the output form. If a form called by the PRLLFORM form activates on an error another logical action with the QUIT command, the latter logical action should also call the next form of the PRLLFORM form. The command should be: QUIT;Form <formnumber> If any of the forms called by the PRLLFORM formexcept the last formhave any non-logical actions, the non-logical actions should be moved to the last form called by the PRLLFORM form. Activating any action in the forms called by the PRLLFORM formexcept the last closes the previous forms in the flow.

12

Background Pressing <Alt>+<a> (used to open a new line in a multioccurrence form) is not supported in i.way. What to do command. Consider defining an action that invokes the INSEMPTYOCC

13

Background Using TCP/IP protocolinstead of HLLAPImay increase CPU consumption and/or cause changes in memory usage for the CICS region. What to do Tune and check the application to optimize its CPU consumption and/or its memory usage, including a load test of the application. Contact your local Support Center for assistance.

a.4

Differences between i.way and Sapiens Workstation

1 i.way uses absolute positioning and, thus, maintains precise layout for eMerge application screen objects (e.g. fields, images). Screen objects displayed via i.way are displayed at the same coordinate positions as these objects are displayed on the equivalent Sapiens WorkStation forms. 2 The SEPTRAIL option (i.e. displays the fields trailer on a separate line) is not supported. 3 The DETAIL command is not supported. 4 Hexadecimal fields cannot be displayed together in one Editdrop or Listbox. 5 The More system action is not available.

a-15

To i.way from Sapiens Workstation Differences between i.way and Sapiens Workstation

6 Only textual help on the field level is available. 7 DDE (in both directions) is not supported; OLE is supported. 8 The Invisible option hides the field value in a form (i.e. the field appears to be blank). The Password option shows the field value as asterisks (i.e. ***). 9 The initial setting for the ACCEPT command is ACCEPT ALL. 10 The default display type for a field with distinct possible values is ListDrop. 11 For a field defined with a background color, assigned the NoFrame option, and there is no data in the field value, the color of the field without the data is the field background color. In Sapiens Workstation, the field without the data is the color of the form. 12 A select form for a date field can be accessed by clicking the Select Value button and not by clicking the field. 13 The following table shows which system actions are available when using Internet Explorer and Netscape to access an eMerge application: Key Equivalent 1 2 3 4 5 6 7 8 24
HELP SELECT QUIT NEW CONTINUE MORE PREVIOUS NEXT ZOOM

Name

Internet Explorer 4.01 3 3 3 3 3 3 3 3 3 3 3 3 3

Netscape 4.5

14 For a field with display type ListDrop, any click (single or double) on the field displays the select form (i.e. all the fields on the select form not assigned Ignore are displayed). 15 The NULLSON option (NULL character is used instead of underscore in the field value) is not supported. Blank fields are displayed with the default background color defined for the field.

a-16

To i.way from Sapiens Workstation Differences between i.way and Sapiens Workstation

16 The NOTIFY ON command works correctly. Notification messages are displayed for successful updates. 17 The AUTOSKIP command has no effect when a field value is changed, so that the last character in the new value stays the same as the last character in the old value. 18 If you make a form window so small that not all the form objects are displayed in the window, scroll bars are automatically added so you can see all of the form objects.

a-17

To i.way from Sapiens Workstation Differences between i.way and Sapiens Workstation

a-18

Appendix b To i.way from 3270

b.1

Moving to an i.way-Display
Applications that were developed for access via 3270 terminals and now will be accessed via i.way must be reviewed and in some cases modified. Moving to an i.way-based (web-based) display requires changes to existing and development of new forms. Existing forms may need to be modified to take advantage of the benefits of i.way-based display. New forms (both data forms and menus) should be defined that take advantage of the i.way-based display. The procedure for developing forms accessed via i.way is not the same as the one for forms accessed via 3270 terminals. The new procedure lets you take advantage of the i.way-based features. This chapter describes how to modify existing application forms that were developed for access via 3270 terminals and now will be accessed via i.way. The chapter contains the procedure for modifying 3270 forms and a set of considerations for 3270 forms.

b.2

Modifying 3270 Forms

This section gives a set of steps to be followed for forms that were developed for access via 3270. The steps include the following:

BackgroundUnder what conditions the step should be done. What to doExactly what should be done. If the step includes a query, the query number and needed parameters are given. ResultA description of the modifications that were done and what further actions may need to be done for this step.
All forms that are modified via the specified queries must be reloaded by clearing the local database. See i.way Installation & Administration or i.station Installation & Administration.

b-1

To i.way from 3270 Modifying 3270 Forms

Background A review should be done to decide if the 3270 forms will be used for i.way. What to do If the same forms will not be used, duplicate the 3270 forms. Define a different flow if the application is run in parallel by i.way and 3270 terminals.

2 3 4

Assign the Parallel option to forms accessed via i.way. Define a set of templates (for data entry forms, menus, etc.) and update the duplicated 3270 forms to use the templates. Background Grouping and Sub fields are not supported in i.way. Forms that contain these fields must be identified and redesigned. What to do Run Query 1683.

Result Finds the forms that contain Grouping and Sub fields so they can be redesigned. 5 Background For 3270 forms, forms may contain inherited actions. These must be identified. Inherited actions are not recommended for use in i.way forms. What to do Parameters From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Result Finds the forms that contain inherited actions. Assign the Local option to the action. This avoids inheritance. 6 Background Non-fixed occurrences (i.e. the Occurrences field for the block in the form is defined as less than zero) can be problematic in i.way if any form objects are placed under the block in the form. A. What to do Parameters From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Run Query 1653. Run Query 1680.

b-2

To i.way from 3270 Modifying 3270 Forms

Result Finds the forms that contain blocks with the Occurrences field for the block in the form defined as less than zero. B. What to do For blocks with the Occurrences field for the block in the form defined as less than zero, define a fixed occurrence (i.e. greater than or equal to zero). 7 Background Consider defining the Previous and Next actions for multioccurrence blocks. What to do For multi-occurrence blocks, run Query 1654 twice: once for Previous and once for Next. Parameters From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. PF No.The number of the action. WidthThe width in pixels of the action. HeightThe height in pixels of the action. Button CksThe option that determines how the action is displayed: 0040 for HyperImage. BLP CommandThe command called by the action: Previous or Next. Image FileThe file of the image to be placed on the new action. File ExtThe file extension of the image to be placed on the new action: jpg or png. Client Block No.The number of the block in the range of forms that needs the Previous or Next button. Result Inserts the Previous or Next button in the block according to the parameters entered in the query. 8 Background In i.way, the DETAIL command is not supported. The forms that use the DETAIL command must be identified and redesigned. What to do Via the Tools tab, right-click Form Information and choose BLP Commands in Forms. The BLP Commands Information (100039) form is displayed. Search for the DETAIL command for all three options (i.e. Private Commands, Menu Options and Entry/Exit Commands). Result Finds the forms that use the DETAIL command.

b-3

To i.way from 3270 Considerations for 3270 Forms

b.3

Considerations for 3270 Forms

The following considerations should be made when moving from 3270 to i.way: 1 Background What to do option. Background All flows should be checked. For big applications, use the List Flow utility with NOSCRN All calls for forms via BLP commands should be checked.

What to do Via the Tools tab, right-click Form Information and choose BLP Commands in Forms. The BLP Commands Information (100039) form is displayed. Search for the FORM command for all three options (i.e. Private Commands, Menu Options and Entry/Exit Commands). 2 Fields do not need to be displayed in a form in the same order they are defined in the operation. Consider defining a new tab-order for forms that have fields that are not shown in the same order as in the operation. Consider displaying field names in titlecase. What to do Parameters From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Result All field names are changed to titlecase. However, check the results for there may be words in the field names that should not be titlecase; e.g. acronyms. 4 5 Consider adding tooltips for actions. Consider using display types other than the default display types; ListBox, OptionButton, etc. for fields with possible values and for fields for which a Subject was defined. Consider adding titles for forms in place of the names given when the form is first defined. Background For 3270 forms, a form could contain both blocks and menu options. This is not supported in i.way. Thus, in i.way, a form that contains both blocks and menu options should be split into two forms: Run Query 1659.

6 7

b-4

To i.way from 3270 Considerations for 3270 Forms

one form with blocks and an action that calls a menu and the second form a menu containing the relevant menu options. What to do Parameters From FormThe number of the first form in the range of forms that must be checked. To FormThe number of the last form in the range of forms that must be checked. Result Finds the forms that contain both blocks and menu options. Using the output list, make a copy of each of the relevant forms (forms that contains both blocks and menu options). The copy is used for the menu; the original form is used for the blocks and the action that calls the menu.

Run Query 1677.

In the original form: delete the menu options define an action that calls the menu In the copy of the form: delete all the blocks delete all unnecessary actions and definitions (e.g. error overrides) via Form Editor, define a template for a menu and add any needed GUI definitions

Background The + operation code that is used to open a new line in a multi-occurrence form is not supported in i.way. What to do command. Consider defining an action that invokes the INSEMPTYOCC

Background Using TCP/IP protocolinstead of accessing applications via 3270 terminalsmay increase CPU consumption and/or cause changes in memory usage for the CICS region. What to do Tune and check the application to optimize its CPU consumption and/or its memory usage, including a load test of the application. Contact your local Support Center for assistance.

b-5

To i.way from 3270 Considerations for 3270 Forms

b-6

Appendix c Sample Database Used in Queries

The sample database used throughout Part G Reports and Queries was based on the following database structures:

c-1

Sample Database Used in Queries

The data used in the database:

c-2

Sample Database Used in Queries

c-3

Sample Database Used in Queries

c-4

Appendix d Using Constructors

d.1

What is a Constructor
In earlier versions, in order to create the data structures (i.e. composites, classes and fields) eMerge provided constructors (formerly called tables). The constructor is a tool for creating composite and class structures. Based on the constructor definitions, and the associations defined between them, not only are the required data structures created, but part of a complete application is generated. The application generated covers the three necessary aspects of a complete application:

data logic presentation

Data
For each constructor, a class within a composite is generated. If the constructor is defined as a root constructor, a new composite is generated with a root class. If it is defined as a dependent constructor, a class is generated in an already existing composite.

Logic
The operation needed to retrieve and update the data is generated. All the fields that comprise the constructor are in the operation. Thus, all the information that makes up each occurrence can be accessed. Hidden rules are generated to maintain referential integrity between the fields within its classes. Thus, when an occurrence of a parent is deleted, all related occurrences of its dependent classes are deleted as well.

d-1

Using Constructors What is a Constructor

Conversely, before a dependent class occurrence is inserted, the related parent class occurrence must exist.

Presentation
The data forms (representing the classes) needed to populate the database with the application data, and a basic flow between the forms are generated. The data forms are for a single-occurrence form and for a multi-occurrence form. The following diagram shows what is generated by a constructor:

C on st ru ct o r Data composite Presentation multi-occurrence form single occurrence form

root or dependent class

fields

Logic operation

hidden rules for referential integrity

During initial application development, the data structures are built and configured using the constructor. Later, when modifying the application, the composite, class and field definitions may be accessed directly. The following are some of the things that can be done via the constructor basic path: assigning a foreign key, defining a subject constructor for a field, accessing and defining referential integrity, extending field definitions and using synonyms.

d-2

Using Constructors Assigning a Foreign Key

d.2

Assigning a Foreign Key

Requests for data from the database are handled via operations. An operation is defined with a set of fields and a target class in the database where the data is stored. A request for data results in the necessary data being read from the target class and displayed. Data that is not included in the class can be accessed via a foreign key. A key field in a constructor that is also a field in another constructor is referred as a foreign key field in the other constructor. The source constructor, where the field is defined as the key, is the subject constructor for the field. By defining the source constructor as a subject constructor for the key field, it can be used as a lookup constructor for any constructor where the key field is included as a foreign key.

FLDA is the key field of constructor 1. In constructor 2, FLDA is a foreign key field. Constructor 1 is the subject constructor for FLDA. Use a subject constructor for the following:

To ensure referential integrity of data: a value defined to a foreign key field must exist in the subject constructor. For example, an employee

d-3

Using Constructors Defining a Constructor as a Subject Constructor

must have been defined in the Employee constructor before the employee can be added to a department in the Department constructor.

To look up, in the subject constructor, the available values of the foreign key and to select a value to be included in the current constructor. To zoom in on details about the foreign key in the subject constructor. To look up values of related fields in the subject constructor and to use them in the current constructor. If the target class for the operation displayed on a data entry form contains a foreign key field, you can display a field from the subject constructor on the data entry form. For example, if the employee number is a foreign key in the Department constructor, you can include the employee name from the Employee constructor in the Department data entry form.

d.3

Defining a Constructor as a Subject Constructor

A subject constructor is a constructor containing a key field that is also used in another constructor (as a foreign key field).

d-4

Using Constructors Defining a Constructor as a Subject Constructor

Defining a Subject Constructor

1 From the model, right-click the concept and choose Object > Constructor (Basic) Path. The Constructor form is accessed displaying the constructor definition which contains the foreign key field as its key:

The subject constructor must be an independent constructor (i.e. without a parent constructor).

d-5

Using Constructors Defining a Constructor as a Subject Constructor

2 With the pointer on the key field, click the Details button in the Fields groupbox. The Constructor: Field Details form is displayed:

3 Assign the Entity option to the key field. The Entity option establishes the field as the key field for the constructor (as if the Key option was assigned) and also establishes the constructor as the subject constructor for the field. Example: In the Employee constructor, the Dept No field is a foreign key field (it is the key field for the Department constructor). Instead of using the possible values meaning to display the department name you can define the Department constructor as the subject constructor for the

d-6

Using Constructors Defining a Constructor as a Subject Constructor

Dept No field. (The key field of the Department constructor is assigned the Entity option.)

Viewing the Connection via the Referential Integrity Form

The connection between the field (Dept-No) and the subject constructor (Department) can be seen via the Referential Integrity form. 1 With the pointer on the key field (Dept-No) of the Department constructor click the FieldDef button in the Fields groupbox. The Constructor: Field Definition form is displayed. 2 Click the Subject button. The Referential Integrity form is displayed:

d-7

Using Constructors Defining a Constructor as a Subject Constructor

Cross-Constructor Referential Integrity

The Department constructor also includes the Manager No field. This field is defined as being the Employee No field, originally defined in the Employee constructor. If the Employee No field, in the Employee constructor, is assigned the Entity option, the Employee constructor becomes a subject constructor for the Employee No field. You can see this via the Referential Integrity form. 1 With the pointer on the Manager No field of the Department constructor click the FieldDef button in the Fields groupbox. The Constructor: Field Definition form is displayed. 2 Click the Subject button. The Referential Integrity form is displayed:

d-8

Using Constructors Implementing Referential Integrity

The association between the Manager No field and the subject constructor is shown, as well as the association between the Manager No field and the Employee No field in the subject constructor.

d.4

Implementing Referential Integrity

Once a subject constructor is defined, referential integrity between the foreign key field and the subject constructor is enforced. Example: An attempt to define a manager in a department, where the manager does not exist in the Employee constructor, fails (manager 13 does not exist in the Employee constructor):

d-9

Using Constructors Selecting a Value and Zooming in on a Value from the Subject Constructor

Only one of the four employees shown in the Employee data entry form can be entered as manager in the Department data entry form. Deleting an employee does not cause an error, even if the employee is defined as a manager in the department constructor.

d.5

Selecting a Value and Zooming in on a Value from the Subject Constructor

When you define a subject constructor, a select form and a zoom form are automatically defined. Wherever the key field of the subject constructor appears in a data entry form, clicking the Select Value button accesses the select form and clicking the Zoom button accesses the zoom form. For more details refer to Chapter 38, Select and Detail Forms. The connection between the field and the Select form and the Zoom form can be seen via Select and Detail fields in the Forms subgroupbox of the Referential Integrity form:

d.6

Using Related Values From the Subject Constructor

Once a constructor has been defined as a subject constructor, fields from the constructor can be included in data entry forms, in order to display information from the subject constructor. Retrieving a field from the subject constructor, based on foreign key fields, is called decoding. The opposite, retrieving the foreign key field from the subject constructor, based on a NAME field, is called encoding.

d-10

Using Constructors Using Related Values From the Subject Constructor

Example
In the example, Dept Name (a field defined in the subject constructor Department) is displayed on the Employee user form together with Dept No a foreign key field.

Positioning the pointer in the Dept No field and clicking the Select Value button causes the display of the Department data entry form. Selecting a value by positioning the pointer in the line displaying the relevant value and clicking the Quit button returns to the Employee data entry form with the Dept No field filled in. Pressing <Enter> results in the Dept Name field also being filled in. However, the department name is not stored along with the department number in the Employee constructor.

Including Fields from a Subject Constructor in a Form

You can include fields from a subject constructor in a data entry form. 1 Access the Constructor form and display the constructor definition which contains the foreign key field. 2 Define fields from the subject constructor in the current constructor (after the foreign key field). 3 With the pointer in each field defined, click the Details button and assign the field the DefaultSubject option: The DefaultSubject option means that the field value is taken, by default, from the subject constructor.

d-11

Using Constructors Using Related Values From the Subject Constructor

Fields included from the subject constructor and assigned the DefaultSubject option are for display purposes only and consequently they are protected in the data entry form. 4 Specify the subject constructor information in the Source subgroupbox of the Fields groupbox (do not enter values for Data Type and Size). 5 In order to allow entry of a value in the field, assign the VerifySubject option to the field:

Value Checking
When the VerifySubject option is assigned, a value entered for the field is checked against the foreign key field value in the subject constructor. The respective value of the foreign key must also be entered in the data entry form and the two values must match in the subject constructor. Example: The foreign key value (the Dept No field) does not match the department name:

Using the Name Option

If the Name option was assigned to the field assigned the VerifySubject option (in the subject constructor), you can enter a value to the field without entering a value for the foreign key field. The corresponding value for the foreign key field is retrieved (via the lexicon) and displayed in the data entry form.

d-12

Using Constructors Defining Several Subject Constructors for the Same Field

Example: The foreign key value (the Dept No field) was not entered, although the department name was entered:

d.7

Defining Several Subject Constructors for the Same Field

If the same field is used in more than one constructor as the key field, each constructor can be used as a subject constructor. This is called alternative referential integrity. Either referential integrity or alternative referential integrity is defined for the constructor, depending on the source constructor.

Both the Employee and the Tax constructors use the Employee No field as the key field. The Employee constructor is defined as the subject constructor (i.e. the Employee No field in the constructor is assigned the
d-13

Using Constructors Defining Several Subject Constructors for the Same Field

Entity option). The Employee No field can be assigned the Entity option in only one of the constructors. Thus the Tax constructor is defined with the Employee No field as a key field and not as an entity field:

An attempt to assign the Entity option to the Employee No field, after assigning it to the same field in the Employee constructor, results in an error. The Tax constructor behaves towards the Employee subject constructor as described in "Implementing Referential Integrity" on page d-9. That is, an employee inserted in the Tax constructor must exist in the Employee constructor; the Employee Name field, from the Employee constructor, can be included in the data entry form for the Tax constructor. The Department constructor includes the Manager No field, which is linked to the Employee No field for referential integrity purposes. Depending on the application, the subject constructor for the Manager No field can be either the Employee constructor or the Tax constructor.

Using the Constructor Whose Key Field has the Entity Option
To assign the Employee constructor as the subject constructor for the Manager No field, the Manager No field is defined in the Department
d-14

Using Constructors Defining Several Subject Constructors for the Same Field

constructor with the Employee constructor number in the Constructor field of the Source subgroupbox. Inserting the Employee Name field with the DefaultSubject option in the constructor results in the Employee Name field being included in the data entry form:

This is the same definition as the subject definition described in the example on page d-6. The values for the Employee Name field are taken from the Employee constructor, based on the value of the Manager No field.

Using the Constructor Whose Key Field has the Key Option
To set the Tax constructor as the subject constructor for the Manager No field, define the Manager No field in the Department constructor with the

d-15

Using Constructors Defining Several Subject Constructors for the Same Field

Tax constructor number in the Constructor field of the Source subgroupbox and assign the SplitSubject option to the field:

Assigning the SplitSubject option defines the Source Constructor field (in this example the Tax constructor) as the subject constructor for alternative referential integrity for the field. Inserting the Salary field with the DefaultSubject option in the constructor, as shown above, causes the field to be included in the data entry form. The values for the Salary field are taken from the Tax constructor, based on the value of the Manager No field.

Viewing the Definition of the Alternative Referential Integrity

To see the definition of the alternative referential integrity, position the pointer in the Manager No field and click the FieldDef button. The Constructor: Field Definition form is displayed. Click the Subject button, the Referential Integrity form is displayed. The alternate referential integrity information is displayed in the Alternate referential integrity groupbox.

d-16

Using Constructors Introduction to Reengineering

For the Manager No foreign field, in the Department constructor, the Tax constructor is the subject constructor. In the subject constructor, the Employee No field is the field that equates to the Manager No field. If the field in the current constructor (Manager No in the example) is the same as the field in the context constructor (Employee No), the Field textbox in the Source subgroupbox is left empty.

d.8

Introduction to Reengineering
The following processes are termed reengineering: Obtaining a constructor from primary data objects, i.e. from a class in a composite. See "From Primary Data Objects to Constructor" on page 17.

Obtaining a concept Model from a consrtuctor. Using Modeler for your development tool, you obtain the capability to visualize and designvia conceptscomplex applications in a graphic way. Modeler automatically creates the data structures necessary to support the concept created via Modeler. The data structures include a constructor for each implemented concept and implemented design. If you have an existing constructor that you want to incorporate into a concept model, you can create a concept in the concept model that is based on the existing constructor. See "From Constructor to Concept Model" on page 22.

d.9

See the Business Integrity Server Administration Guide for information on the tuning requirements recommended for reengineering a constructor to a concept Model.

From Primary Data Objects to Constructor

Reengineering Tools provides a set of queries that are used to perform reengineering from primary data objects to the constructor.

To access Reengineering Tools:

1 From the Navigation pane of Development Workbench select the Tools tab. 2 Select Reengineering Tools. The Reengineering Tools (100026) menu is displayed:

d-17

Using Constructors From Primary Data Objects to Constructor

All the queries listed below produce files for batch update. Make a backup before updating.

Vertical Queries

All vertical queries defined for the previous version 43.32, should be run before running the queries listed below. Those vertical queries are not listed here.

Run the following vertical queries: Query 405fixes internal status of constructors. Query 401updates the constructor number to operations that have constructor. Query 402 removes the constructor number from operations that have no constructor. Query 403updates/fixes constructor number of classes that have constructor.

d-18

Using Constructors From Primary Data Objects to Constructor

Query 404removes the constructor number from classes that have no constructor.

After the vertical queries listed above are run, proceed to run the queries listed below depending on the following: Constructors do not need any correction (do not run any of the queries listed below). Constructors need minor correction (either a majority or a minority, see "Constructors Need Minor Correction" on page 19). Constructors need major correction (see "Constructors Need Major Correction" on page 19.

Constructors Need Minor Correction

1 Manually change the constructor status to D (Development) for constructors with correct definitions or with fields mismatching in field options. 2 Select the Fix Field Options of Cns in D option to fix field option mismatches (for constructors with status not equal to R).

Constructors Need Major Correction

If constructor definitions must be rebuilt then: 1 Select the Change Cns Status to R option to change the status of each constructor to R (Reengineering). 2 Manually delete all the constructors (they are redefined in step 8). 3 Constructors with field mismatches in the class or operation can only be fixed manually or by deleting the fields from all constructors with status R using the Delete all Cns Fields option. The deleted fields are reinserted in step 9 using the Insert New Dependent Cns option. 4 Select the Define New Opers for Cns in R option to define new operations for constructors with status R that do not have the Operation Only or Banner option assigned. The file produced by this query contains new operations with names: ENG CNS||#1901, and number 11111. Manually update the operation numbers in this file with real operation numbers. 5 Select the Update Cns with New Operations option to update the constructors with status R that had new operations specified via the Define New Opers for Cns in R option (step 4). 6 Select the New Opers-Classes without Cns option to define new operations for classes without constructors. The file produced by this
d-19

Using Constructors From Primary Data Objects to Constructor

query contains new operations with names: ENG CLS||#1901 and number = 11111. Manually update the operation numbers in this file with real operation numbers. 7 Define fields for all new operations that have names that start with ENG * and that were produced via the Define New Opers for Cns in R and the New Opers-Classes without Cns options (steps 4 and 6): Select the Define Fields to New Operations option to define the fields in the operation (class 401). This query produces a file in free format. A User card must be added to this file. Run the file on the DB with language set to one language. If there is an occurrence without any field, it means that the class has no fields and a decision to delete such a class (as garbage) must be made. Select the New Operations Need Path Field option to create path fields (the Define Fields to New Operations option does not produce path fields). Use this option to find all the new operations with names starting with ENG * that need path fields added. 8 Define constructors for all classes that have no constructors: Select the Insert New Root Constructors option to create new root constructors for root classes. The file produced should be checked and updated (if required). Select the Insert New Dependent Cns option to create new dependent constructors.

Note: This query updates Parent Constructor = Root Constructor and Use = Many for all dependent constructors. Such constructors must be fixed manually for constructors of level = 3 or higher and OneToOne (0) if needed, using the composite structure.

9 Select the Insert Field to Cns in R option to insert fields into all new constructors (that were produced in step 8) and into constructors with status R without any field (that were produced via the Delete all Cns Fields option, step 3). 10 Fix the constructor triggers: Select Triggers. The ReEngineering Constructor Triggers menu is displayed:

d-20

Using Constructors From Primary Data Objects to Constructor

Select the Delete All Constraints option to delete occurrences of class 1902. Select the Delete All Consequences option to delete occurrences of class 1903. Select the Delete All Issue Rules option to delete occurrences of class 1905. Select the Delete All Edit Rules option to delete occurrences of class 1906. Select the Insert Constraints from Class option to insert class triggers into class 1902. Select the Insert Issue Rules from Oper option to insert issue rules of the operation into class 1905. Select the Insert Edit Rules from Oper option to insert edit rules of the operation into class 1906.

11 Select the Change All Cns Status to D option to change the status of all constructors with status R to status D.

d-21

Using Constructors From Constructor to Concept Model

d.10 From Constructor to Concept Model

When concepts are created via Modeler and advanced to the implementation stage, the data structures necessary to support the concept (composite and class definitions) and a constructor are created for the concept based on the concept design. The fields of the concept become the fields of the constructor. In the constructor-to-concept model reengineering process, a concept is created via Modeler based on an existing constructor definition. The fields of the constructor become the fields of the concept. When the reengineered concept is implemented, no new constructor is created for the concept. Instead, the concept is based on the existing constructor. The implemented reengineered concept behaves as a "regular" concept in the concept model. Thus, after implementation, Modeler manages both the concept and the constructor on which it is based, in the same way as it manages concepts and constructors created via standard Modeler concept engineering. For example, you can add fields to the concept, define a rule model, link the concept to other concepts, etc. Moreover, any changes made to the concept definitions after implementation, are also reflected in the definition for the constructor on which the concept is based.

d-22

Using Constructors Overview of Reengineering a Constructor to a Concept Model

Concept Engineering
analysis design implementation

concept

concept

concept

constructor

new

Reegineering

concept

concept

concept

existing

constructor
existing

constructor

d.11 Overview of Reengineering a Constructor to a Concept Model

Reengineering a concept hierarchy introduces an existing constructor hierarchy into your concept model. Once reengineering is complete (after the concept is implemented), the reengineered concept can be treated as a regular concept in the concept model. Below is an overview of the procedure to include a constructor (or a hierarchy of constructors) into a concept model: 1 Define a concept via Modeler for each existing constructor: For each existing constructor in the existing constructor hierarchy you have to define a new concept (via Modeler). You define a concept by specifying:

The name of the concept. The concept type (i.e. entity, weak entity, association or document).
d-23

Using Constructors Considerations for Reengineering a Constructor to a Concept Model

The existing constructor on which the concept is based. For a weak entity or an association, the appropriate cardinality and probability. For an association only, two constructors may be specified (a Main constructor and an OppositeToMain constructor). The Main constructor is the dependent constructor of the parent constructor on which the main parent concept is based and the OppositeToMain constructor is the dependent constructor of the parent constructor on which the second parent concept is based. The structure for the concept design can be changed from the default structure of Dependent to Concatenated. The fields of a weak entity with link Joined (cardinality= one, probability = Mandatory) are joined to its parent concept. The path, key, and name fields of the second parent, for an association with link Joined, are joined to the fields of the main parent. It is therefore required to indicate, for each field in the parent constructor, to which concept it belongs (weak entity or association).

2 Customize the Concept Definition (optional)

3 Implement the Concepts to Complete the Reengineering

When the concept hierarchy is implemented, information is automatically copied from the existing constructors to the concepts, creating an implemented reengineered concept. For example, concept fields, design fields, and required triggers are created based on the constructor definitions.

After reengineering is completed, the reengineered concepts behave as regular concepts in the concept model. Fields can be added, rules specified, and links to other concepts defined. With respect to the existing constructors used in the reengineering process, the reengineering process is non-intrusive. That is, the original definitions for the existing constructors (fields, etc.) are not affected by the reengineering process.

d.12 Considerations for Reengineering a Constructor to a Concept Model

The following considerationswith respect to the concept created via Modeler and to the existing constructor on which the concept is based must be adhered to when performing reengineering:

d-24

Using Constructors Considerations for Reengineering a Constructor to a Concept Model

Concept Considerations

Depending on the existing constructor, the concept can be an entity, weak entity, association, or document. The concept must be a new concept. The concept cannot have any user-specified or system definitions, for example: The concept cannot have any fields specified. The concept cannot have any rules attached. Any parent concepts for the concept must be in the design or implementation stage. In a concept hierarchy (parent concept with dependent concepts), a parent concept must be based on a parent constructor and a dependent concept based on a dependent constructor. In a concept hierarchy, a dependent concept that is a weak entity or an association having a link of Joined cannot be a parent of another concept. However, its parent can be the parent of its dependent.
parent concept
entity

dependent concept
with link Joined

dependent concept

Constructor Considerations

The constructor that is used for reengineering a concept cannot be used for any other concept except for one of the following: a weak entity with a link of Joined. an association with a link of Joined that is linked to the parent of the concept. The use for the constructor must be compatible with the cardinality and probability of the concept and vice versa. If the constructor has a use of OperationOnly or Banner, reengineering must be performed at the design level. A dependent constructor (one that has a parent constructor) cannot be used for reengineering a concept that is an entity.

d-25

Using Constructors Reengineering a Concept Based on an Existing Constructor

Following is a list of considerations organized according to the type of concept (entity, weak entity, association, document) that is linked to the existing constructor: Constructors used to Reverse Engineer Entity Concepts

The first field of the constructor must be a key field. The constructor cannot have any parent key fields. If the first key of the constructor references by subject the constructor composite/class, then the concept based on the constructor must be an entity and cannot have a parent. If the entity is in a dependency association with another entity, then the keys of the other entity must be defined in the constructor and their order must be the same as that in the constructor of the other entity. An existing constructor that is used to reverse engineer a weak entity with a link of Many must have at least one key field.

Constructors used to Reverse Engineer Association Concepts

The constructor cannot have any Name fields. The key fields of the second parent concept must be defined in the main constructor If a second constructor is specified, the key fields for the main parent concept must be defined in the second constructor. An existing constructor that is used to reverse engineer an association having a link of Many must have at least one key field.

Constructors used to Reverse Engineer Document Concepts

The constructor cannot have any Name fields. The constructor must have the Document option assigned. The constructor can only have one key field and it must be a Numeric field. The constructor can only have one text field and it must be a Character field.

d.13 Reengineering a Concept Based on an Existing Constructor

To reengineer a concept based on an existing constructor:

1 Insert a concept to represent the constructor into your concept model by choosing the type for the concept (entity, weak entity, association, document). A different dialog box is displayed as per the concept type:

d-26

Using Constructors Reengineering a Concept Based on an Existing Constructor

Entity

A rectangle representing the weak entity appears in the model, and the Entity dialog box opens:

Weak Entity

A trapezoid representing the weak entity appears with a line connecting it to its parent, and the Weak Entity dialog box opens:

If the link specified for the weak entity is Joined, and reengineering is being performed, the name and number of the constructor on which the parent concept is based is automatically displayed in the Reengineering Constructor Name textbox:

d-27

Using Constructors Reengineering a Concept Based on an Existing Constructor

For an Association

A hexagon representing the association appears with lines connecting it to the parent concept or concepts, and the appropriate Association dialog box opens. The Recursive Association dialog box is identical to the Association dialog box, except that it has the Prefix text boxes.

d-28

Using Constructors Reengineering a Concept Based on an Existing Constructor

For a Document

A parallelogram representing the document appears with a line connecting it to its parent, and the Document dialog box opens:

For more details on how to define a new concept see Chapter 2, Analysis StageBuilding a Concept Model. 2 Click the New button. 3 Enter a name for the concept in the Name textbox. 4 In the Reengineering section of the dialog box, in the Constructor Name textbox, enter a name for the existing constructor on which the concept is based. If you do not know the constructor name, place the pointer in the Constructor Name textbox and click Find. A list of existing constructors in the knowledgebase is displayed. Select a constructor from the list. 5 Click OK. The concept is displayed in the concept model in the design stage of development. It is marked as a reengineered concept in the model by a red frame around a yellow concept:

6 If required you can modify the Structure from the default value of Dependent to Concatenated by right-clicking the concept and choosing Object > Concept Design from the pop-up menu that is displayed. The

d-29

Using Constructors Reengineering a Concept Based on an Existing Constructor

Concept Design form is displayed. Select Concatenated from the Structure drop-down listbox. Click OK. 7 Return to Modeler. Implement the concept by clicking the Implement button on the Development Workbench toolbar. If successful, the color of the concept changes to green with a red frame:

When the concept is advanced to the implementation stage, a new constructor is not created. Instead, information needed for the concept is automatically copied from the existing constructor to the reengineered concept.

d-30

Using Constructors Reengineering a Constructor to a Concept Model Example

d.14 Reengineering a Constructor to a Concept Model Example

The following Employees constructor exists in the knowledgebase and is to be reengineered into a concept in a concept model:

The new Employee concept is created (as an Entity) based on the Employees constructor:

d-31

Using Constructors Reengineering a Constructor to a Concept Model Example

The new Employee concept is created in the design stage (without any field data):

d-32

Using Constructors Manipulations During the Reengineering Process

When the Employee concept is advanced to the implementation stage, the field data from the Employees constructor is automatically copied to the Employee concept:

The reengineered Employee concept is now a regular concept (based on the Employees constructor definitions) in the concept model.

d.15 Manipulations During the Reengineering Process

During the reengineering process of a constructor to a concept model there is a concept design manipulation that is allowed and there are certain other manipulations for concepts that are not allowed.

Concept Design Manipulation

In some cases you may be required during reengineering, to modify the structure definition for the concept design. Example: Two existing root constructors: constructor Bank (3500) having a key field Bank ID and constructor Branch (3600) having key
d-33

Using Constructors Manipulations During the Reengineering Process

fields Bank ID and Branch ID are to be used to reverse engineer a concept named Bank of type Entity and a dependent concept named Branch of type Weak Entity. By default, the concept design for the Branch concept is assigned a structure definition of Dependent, since it is a weak entity (dependent concept). However, the Branch (3600) root constructor upon which the Branch dependent concept is based, has a structure that does not match the dependent structure of the dependent Branch concept and this causes an error to be issued in the implementation stage. To reflect the reengineered concept hierarchy, the structure definition for the dependent Branch concept must be changed to Concatenated. Reengineered Entity and Weak Entity
existing root constructors Bank
3500

concepts

Branch
3600

Bank
entity

default design structure: Dependent change design structure to: Concatenated

Branch
weak entity

To modify the concept design structure:

1 Via Modeler, select the concept (that is being reengineered). Choose Object > Concept Design. The Concept: Design form is displayed:

d-34

Using Constructors Manipulations During the Reengineering Process

2 In the Order groupbox choose Concatenated for the structure from the Structure drop-down listbox. 3 Click OK. Weak Entities and Associations with Link Joined For weak entities with link Joined it is necessary to specify its fields in the constructor of the parent concept.

During reengineering, when defining a weak entity (or an association) with link Joined, the name and number of the constructor on which the parent concept is based, is automatically displayed in the Reengineering Constructor Name textbox.

For associations with link Joined it is necessary to specify its fields in the constructor of the main parent concept. A weak entity with link Joined or an association with link Joined are referred to as secondary concepts with respect to the constructor of the parent concept.

To specify the fields of a secondary concept in the constructor of the parent concept:

1 Via Modeler, select the weak entity or association (that is being reengineered). Choose Object > Concept Design. The Concept: Design form is displayed:
d-35

Using Constructors Manipulations During the Reengineering Process

2 Click the RevEngFields button. The Secondary Concept form is displayed with the fields of the constructor listed:

3 Assign the Belongs To option to at least one of the fields of the constructor (except to a path, key or name field). Click Apply. For the fields selected, the name of the weak entity or association that is the secondary concept, is automatically displayed in the Secondary Concept drop-down editbox and the design number is listed in the Design textbox. If the parent concept for the weak entity or association has several secondary concepts, a list of secondary concepts for the parent concept is displayed in the Secondary Concept drop-down editbox. Choose the relevant secondary concept. 4 Click OK.

Other Manipulations
The following manipulations for concepts are not allowed during the reengineering process:

The parent concept of a concept undergoing reengineering cannot be changed. Concept fields or design fields cannot be added to a concept while it is undergoing reengineering.

d-36

Using Constructors Reengineering a Concept Design

DBMS options or any other concept options cannot be changed. The design name and Link cannot be changed. In addition, the following options cannot be changed: Parent Display, Design Status or Design Use. The cardinality and/or probability for an association or weak entity undergoing reengineering cannot be changed. The main parent for the association cannot be changed. If a second constructor is specified for the association, you cannot delete the opposite to main design.

Once reengineering is completed (i.e. the concept is implemented), it behaves as a regular concept in the concept model and most manipulations permitted for a concept in the concept model are also permitted for the reengineered concept.

d.16 Reengineering a Concept Design

You can create a new concept design (physical or operational) for a reengineered concept and base the new concept design on an existing constructor.

To reverse engineer a concept design:

1 Via Modeler, select the concept and click Object > Concept Design. The Concept Design form is displayed. Click the NewDesign button. The Concept: New Design form is displayed:

d-37

Using Constructors Reengineering a Concept Design

2 Enter a number and name for the concept design in the Design textbox. 3 Assign the Physical or OperationOnly option to the concept design. 4 Click Apply. 5 Click the ReverseEng button. The Reengineering form is displayed:

6 In the Reversed Constructor textbox, enter a number and name for the existing constructor upon which the concept design is based.

You cannot base the reengineered concept design on an existing constructor that is already being used for a reengineered concept.

7 Click OK.

d-38

Using Constructors Concepts and Designs After Reengineering

Considerations When Reengineering a Concept Design

The concept of the concept design must be implemented. You cannot reverse engineer an OperationOnly concept design with a link of Joined. The existing constructor upon which the concept design is being based cannot be a constructor that is already in use for a reengineered concept. When the constructor upon which the reengineering is being based has a use of Operation or Banner, then the concept design must have the OperationOnly option assigned.

d.17 Concepts and Designs After Reengineering

Once reengineering is completed (i.e. the concept is implemented), it behaves as a regular concept in the concept model and manipulations permitted for a concept in the concept model are also permitted for the reengineered concept. Nevertheless, you cannot perform any actions that cause the deletion of the existing constructor on which the reengineered concept is based. For example, you cannot change the design link from Many to Joined or to OnlyOne or unassign the Implementation option for a design.

d.18 Retreating From Reengineering a Constructor to a Concept

d-39

Using Constructors Retreating From Reengineering a Constructor to a Concept Model

Model
You can retreat from the reengineering process, either:

While reengineering a concept. After the reengineering of a concept or concept design is completed (i.e. after implementation).

Retreating from Reengineering

existing

constructor
original definitions

analysis concept
no definitions retreat by returning to analysis
d co ele nc tin ep g t

design
existing retreat by returning to design

implemented Concept
existing

constructor
original definitions

concept
some definitions

concept design
existing retreat by

constructor

analysis concept

original definitions

constructor
original definitions

concept

deleting concept

new definitions

existing

constructor
original definitions

A concept can be retreated by:

From the design stage, returning the concept to the analysis stage of development. From the implementation stage, returning the concept to the design stage and then to the analysis stage. Deleting the concept.

Although the reference between the concept and the existing constructor on which it is based is deleted when retreating form reengineering, the reengineering process is non-intrusive and the original definitions for the existing constructor (fields, etc.) are unaffected by retreating.

d-40

Using Constructors Retreating From Reengineering a Constructor to a Concept Model

Retreating During Reengineering (from design)

existing

constructor
original definitions

Retreating from Reengineering

analysis
retreat by returning to analysis

design
existing

concept
no definitions

co concept analysis
retreat by deleting concept

constructor

concept

existing

constructor
original definitions

When you retreat a concept during reengineering, the following occurs: The reference between the existing constructor and the concept is deleted (i.e. the source constructor specification). All concept design definitions specified during reengineering are deleted. All indications made to fields in the existing constructor are removed. For concepts having a link of Joined, any fields joined to the parent concept during reengineering are not deleted, but references to this parent concept are deleted.

d-41

Using Constructors Retreating From Reengineering a Constructor to a Concept Model

Retreating After Reengineering a Concept (from implementation)

existing

Retreating from Reengineering

design
retreat by returning to design

constructor
original definitions

implemented Concept
existing

concept
some definitions

concept design
retreat by

constructor

original definitions

concept

deleting concept

new definitions

existing

constructor
original definitions

When you retreat a concept after reengineering, the following occurs:

All concept designs defined by the user must be deleted by the user. All fields added to the concept after reengineering are deleted from the concept, from the existing constructor on which the concept is based, and from the knowledgebase. All constraints and all consequences defined for the concept are deleted. For concepts having a link of Joined, any fields joined to the parent concept after reengineering, are deleted.

Retreating After Reengineering a Concept Design

A concept design can only be retreated by deleting the concept design. Once the concept design is deleted, all definitions and references to an existing constructor are removed. The original definitions for the existing constructor remain as they were before the concept design was reengineered.

d-42

Using Constructors Reengineered Concepts from Previous Versions

d.19 Reengineered Concepts from Previous Versions

Old versions of reengineering can no longer be used. You can however, still use a reengineered concept (or concept hierarchy) that was reengineered in a previous version (e.g. v3). It is nevertheless, recommended to reverse engineer your concepts with the reengineering version described in this chapter. To reverse engineer the concepts again: 1 Retreat the concept to the design stage of development.

Via Modeler, select the concept and click the Design button on the toolbar of Development Workbench.

2 Remove all references to the constructor on which the concept is based:

Via Modeler, select the concept and click Object > Concept Design to access the Concept Design form. Click the V3-RevEng button. The V3 Reengineering form is displayed:

Enter an asterisk (*) in the Constructor number and name textbox. Click OK to delete the constructor reference.

3 Return to the concept model and retreat the concept to the analysis stage of development. 4 Delete all fields and detach all rulesets defined for the concept.

With the concept selected, click the Fields button on the toolbar of Development Workbench. The Concept form is displayed. Delete all fields defined for the concept. If the concept has rules attached, then with the concept selected, click the Rules button on the toolbar. The rule model for the concept is displayed. Detach all rulesets defined for the concept.

d-43

Using Constructors Reengineered Concepts from Previous Versions

5 Reverse Engineer the concept as described in this chapter, see "Reengineering a Concept Based on an Existing Constructor" on page d-26.

d-44

Appendix e Examples of Presentation Components

e.1

URL Component
Branch to HTML Page
Clicking the Summary button activates the component that displays the HTML page.

Preparing the Component

1 Prepare the HTML page, with the title: "As a customer, you have been able to:" 2 Locate the address of the HTML file:
http://<server_name>/clientsummary.htm

e-1

Examples of Presentation Components URL Component

Introducing a URL Component

1 From the Presentation tab of the Navigation Pane of Development Workbench expand Integration and right-click Components:

2 Select New URL. The URL (818) form is displayed. 3 Enter a unique identifying number (510000) for the component in the first Component textbox. 4 Enter a name (Client Summary) for the component in the second Component textbox. 5 Enter the URL of the component in the Resource field:
http:\\<server_name>\clientserver.htm

6 Click OK.

e-2

Examples of Presentation Components URL Component

The URL (818) form shows the following definitions:

Creating an Instance for a Form

1 Access the form in which you want to place the component and click the Edit mode button. 2 Click the Insert Component button.

e-3

Examples of Presentation Components URL Component

3 Place the pointer in the form, drag and click. A rectangle appears:

4 Click Save, to save the component location information. 5 Right-click the form and choose Properties from the pop-up menu that is displayed. The Data Form (10647) form is displayed. 6 Click the Components button. The Components in Form (10649) form is displayed. 7 Enter a unique Instance Name (Client Summary) for the component instance. 8 Select the URL category. 9 Select the Component ID (510000) from the Component ID listbox. The Component ID and the Component Name are displayed. 10 Select the Location ID, for the component instance, from the Location ID listbox.

e-4

Examples of Presentation Components URL Component

The Components in Form (10649) form shows the following definitions:

11 Save and exit all forms and close Form Editor.

Attaching an Event to a Form Object

The following describes how to attach an event (e.g. OnClick) to a form object (e.g. to the action (button) Summary, located on the HTML form).

The form object must be defined in the knowledgebase before you can attach an event to it. For example, actions are defined via the Form/Menu Actions (100609) form).

1 Access the form in which you want to place the component and click the Edit mode button. 2 Access the definition form for the particular form by right-clicking the the form. Choose Properties from the pop-up menu that is displayed. The Data Form (10647) form is displayed. 3 Click the Events button. The Form Events (10659) form is displayed. 4 Select an event (OnClick) from the Event listbox. 5 Select the component Instance ID that is attached to the event.

e-5

Examples of Presentation Components Script Component

6 Attach the event (OnClick) to the action (to the Summary button) by selecting the number of the action (9) from the Action No. listbox. The Form Events (10659) form shows the following definitions:

7 Save and exit all forms and close Form Editor.

e.2

Script Component
Change the Background Color of a Field
The background color of the field changes according to the value of the field.

e-6

Examples of Presentation Components Script Component

Preparing the Component

1 Prepare the following script:
function ChangeBackgroundColor(event) { var elm = getElement("7008");// "7008" is an eMerge field var quote = elm.value; if (quote == "") return; elm.style.fontWeight="900"; elm.style.fontSize="16"; if (quote <= 1000) elm.style.backgroundColor = "#AEF9A4"; // green else if (quote > 1000 && quote <= 2000) elm.style.backgroundColor = "#7AC1F5";// blue else if (quote > 2000 && quote <= 3000) elm.style.backgroundColor = "#F8FCA9";// yellow else elm.style.backgroundColor = "#FDA8FD"; // red }

In the script "7008" is an eMerge field.

The code changes the background color of the displayed quote, depending on the quote range:

between 11000 the background is green between 10002000 the background is blue between 20003000 the background is yellow higher than 3000 the background is red

Indicate colors by using the following within a script:

#RGB_hexa_ number Example:

elm.style.backgroundColor = "#AEF9A4"; // green

2 Locate the address of the script:

http://<server_name>/Hooks.js

e-7

Examples of Presentation Components Script Component

Introducing a SCRIPT Component

1 From the Presentation tab of the Navigation Pane of Development Workbench expand Integration and right-click Components:

2 Select New Script. The New Script dialog box is displayed:

Access the directory where the script file (hooks.js) is located. If the directory listed is not the directory containing the script file, click Import to access the directory where the script file is located. Select the script file (hooks.js) and click OK. 3 Select and drag the script from the Local knowledgebase node (right pane of window) to the Business Integrity Server knowledgebase (left pane of window).

e-8

Examples of Presentation Components Script Component

4 Enter a unique identifying number (444446) for the component in the Script No. textbox and press <Enter>. The Script (838) form shows the following script and function information:

5 Save and exit all forms.

Creating an Instance for a Form

1 Access the form in which you want to place the component and click the Edit mode button. 2 Right-click in the form and choose Properties from the pop-up menu that is displayed. The Data Form (10647) form is displayed.

e-9

Examples of Presentation Components Script Component

3 Click the Components button. The Components in Form (10649) form is displayed. 4 Enter a unique name (ChangeBackgroundColor) for the component instance in the Instance Name textbox. 5 Select Script for the Category. 6 Select the Component ID (444446). The Component ID and the Component Name are displayed. The Components in Form (10649) shows the following definitions:

7 Click the NewCompnnt button on the Components in Form (10649) form to display the Script (819) form. 8 Enter the component number (444446) and component name (chart_s) in the Component textboxes. 9 Enter the function number (444457) and the function name (ChangeBackgroundColor) that are required for the instance.

e-10

Examples of Presentation Components Script Component

The Script (819) form shows the following definitions:

10 Save and exit all forms and close Form Editor.

Attaching an Event to a Form Object

1 Access the form in which you want to place the component and click the Edit mode button. 2 Access the definition form for the form by right-clicking the form and choose Properties from the pop-up menu that is displayed. The Data Form (10647) form is displayed. 3 Click the Events button. The Form Events (10659) form is displayed. 4 Select an event (OnLoad) for the form from the Event listbox.

e-11

Examples of Presentation Components Script Component

5 Select the component Instance ID (5) that is attached to the event. The Form Events (10659) form shows the following definitions:

6 Save and exit all forms and close Form Editor.

e-12

Examples of Presentation Components JavaApplet Component

e.3

JavaApplet Component
Show a Graph Rather than a Data Table
The component displays a visual graph of statistical information retrieved from the eMerge knowledgebase.

Preparing the Component

The JavaApplet component in this example has dynamic parameters, and is invoked via a script. 1 Prepare the following script function:
function updateChart( e ) { document.all("FRMDIV").style.visibility="hidden"; // Copy back button from hidden form to graph area. var hook = document.all("HOOKBASE").innerHTML; document.all("HOOKBASE").innerHTML = "<A onMouseOver=Link_H(982,event) onMouseOut=Link_H(982,event) onClick=Link_H(982,event) href=javascript:void(0) ><DIV class=NODE STYLE=\"Position:absolute;LEFT:225;TOP:453;WIDTH:74;HEIGHT:70;\ " name=982><IMG class=HPFI alt=\"\" border=0 src=\"/SapWeb/DB/iw/image/BACKU.PNG\" ></DIV></A>"; var block = document.opBlocks.getBlock("20");
e-13

Examples of Presentation Components JavaApplet Component

if ( block == null ) alert("Error block"); var cars = block.getColumnByIndex(1); var claims = block.getColumnByIndex(2); if ( cars == null || claims == null ) alert ("Error data"); var strCars = ""; for ( i=1;i<=cars.length;i++) { if ( cars[i].value != "" ) { if ( i != 1 ) strCars += ","; var t = cars[i].value; strCars+=t.replace(" ", "\0"); } } var strClaims = ""; for ( i=1;i<=claims.length;i++) { if ( claims[i].value != "" ) { if ( i != 1 ) strClaims += ","; strClaims+=claims[i].value; } } document.all("HOOKBASE").style.visibility="visible"; var chart = document.all("chart"); chart.setXAxisLabels(strCars); chart.replaceAllDataY(strClaims); chart.repaint();

This code transfers the number of claims from the form to the component that displays a visual graph of the number of claims by car make. Note that the following line indicates the position and size of the component. This line in the code overrides a location ID, if one has been defined for the instance:
STYLE=\"Position:absolute;LEFT:225;TOP:453;WIDTH:74;HEIGHT:70;\"

2 Locate the already available applet and place it in the required address:
http://<server_name>/Javachart/applet/indColumnApp.class

3 Locate the address of the script:

http://<server_name>/Hooks.js

e-14

Examples of Presentation Components JavaApplet Component

Introducing a JavaApplet Component to the Knowledgebase

1 From the Presentation tab of the Navigation Pane of Development Workbench expand Integration and right-click Components:

2 Select New JavaApplet. The JavaApplet (820) form is displayed: 3 Enter a unique identifying number (40000) and a name (chart) for the component in the Component textboxes. The JavaApplet (820) form shows the following definitions:

4 Click the Properties button to display the JavaApplet: Basic Properties (815) form. 5 Select the APPLET tag from the Format listbox. 6 Indicate the file containing the compiled JavaApplet in the Code textbox.

e-15

Examples of Presentation Components JavaApplet Component

7 Indicate the location (path) of all the JavaApplet classes in the Codebase textbox. 8 Enter the width (400) of the component display in the Width textbox. 9 Enter the height (200) of the component display in the Height textbox. The JavaApplet: Basic Properties (815) form shows the following definitions:

10 Click the Parameters button in the Methods groupbox to display the Parameters (816) form. 11 Select the names of the fields that serve as parameters from the Name listbox. The field number and field name are displayed in the Field No. and Name textboxes. 12 Enter constant values (e.g. 123456) for the fields in the Value textbox.

e-16

Examples of Presentation Components JavaApplet Component

The Parameters (816) form shows the following definitions:

13 Access the Script (819) form to define the java component as an embedded component of the script component (444446, CHART_S) located in file hooks.js and that uses the updateChart function (defined in "Preparing the Component" on page e-1).

In the Component textbox: In the first field enter the ID of the script component (444446). In the second field enter the name of the script component (chart_s). In the Properties groupbox:

Select the language (JavaScript) from the Language listbox. Enter the source path (.../hooks.js) In the Embedded Components groupbox:

Select the Category (Japplet). Select the component Number (40000). In the Functions groupbox:

Select the function (updateChart). Click OK

e-17

Examples of Presentation Components JavaApplet Component

The Script (819) form shows the following definitions:

14 Save and exit all forms.

Creating an Instance for a Form

1 Access the form in which you want to place the component and click the Edit mode button. 2 Click the Insert Component button.

e-18

Examples of Presentation Components JavaApplet Component

3 Place the pointer in the form, drag and click. A rectangle appears:

4 Click Save, to save the component location information. 5 Right-click the form and choose Properties from the pop-up menu that is displayed. The Data Form (10647) form is displayed. 6 Click the Components button. The Components in Form (10649) form is displayed. 7 Enter an Instance Name (chartss) for the component instance. 8 Select the JApplet category. 9 Select the Component ID (40000) from the Component ID listbox. The Component ID and the Component Name are displayed. 10 Select the Location ID, for the component instance, from the Location ID listbox.

e-19

Examples of Presentation Components JavaApplet Component

The Components in Form (10649) form shows the following definitions:

Though this particular component does not require definitions for methods, note that if instances of the component are attached to an event, the component must include definitions for methods.

11 Save and exit all forms and close Form Editor.

Attaching an Event to a Form Object

1 Access the form in which you want to place the component and click the Edit mode button. 2 Access the definition form for the particular form by right-clicking the the form. Choose Properties from the pop-up menu that is displayed. The Data Form (10647) form is displayed. 3 Click the Events button. The Form Events (10659) form is displayed. 4 Select an event (OnLoad) from the Event listbox that activates the instance. 5 Select the component Instance ID (5) that is attached to the event.

e-20

Examples of Presentation Components ActiveX Component

The Form Events (10659) form shows the following definitions:

6 Save and exit all forms and close Form Editor.

e.4

ActiveX Component
Display the System Calendar
This component displays a calendar as long as the form is displayed.

e-21

Examples of Presentation Components ActiveX Component

Preparing the Component

This ActiveX component is part of the computer.

The international ID for the Activex component is: 8e27c92b-1264-101c-8a2f-040224009c02

Introducing an ActiveX Component

1 From the Presentation tab of the Navigation Pane of Development Workbench expand Integration and right-click Components:

2 Select New ActiveX. The ActiveX (837) form is displayed. 3 Enter a unique identifying number (530000) for the component in the ActiveX No. textbox and click <Enter>. 4 Expand the Local Knowledgebase node (right side) to display a list of the ActiveX components defined in the system:

e-22

Examples of Presentation Components ActiveX Component

The ActiveX (837) form lists the components in the system:

5 Select the ActiveX component (Calendar Control).

Display the intefaces for the component by expanding the component name (in the Local knowledgebase window). Delete all unnecessary interfaces by right-clicking the interface name and selecting Delete. Leave only the ICalendar interface. View the methods for the ICalendar interface by expanding the interface. The methods: PreviousDay, PreviousMonth, PreviousWeek, and PreviousYear are required. Delete any other methods that appear by right-clicking the method name and choosing Delete. Drag the component to the Business Integrity Server knowledgebase window (left side).

e-23

Examples of Presentation Components ActiveX Component

The ActiveX (837) form shows the following:

6 Save and exit the Activex (837) form.

Creating an Instance for a Form

1 Access the form in which you want to place the component and click the Edit mode button. 2 Click the Insert Component button. 3 Place the pointer where you want the component to appear in the form, drag and click. A rectangle appears. Resize the rectangle, if necessary, by dragging the rectangle handles.

e-24

Examples of Presentation Components ActiveX Component

4 Click Save, to save the component location information. Note the number shown in square brackets on the status bar. This is the LOCATION ID for the visible component. 5 Right-click the form and choose Properties from the pop-up menu that is displayed. The Data Form (10647) form is displayed. 6 Click the Components button. The Components in Form (10649) form is displayed: 7 Enter an Instance Name (Calendar) for the component instance. 8 Select the ActiveX category. 9 Select the Component ID (530000) from the Component ID listbox. The Component ID and the Component Name are displayed. 10 Select the Location ID (2), for the component instance, from the Location ID listbox. The Components in Form (10649) from shows the following:

11 Click the NewCompnnt button in the Component in Form (10649) form to display the ActiveX (821) form. 12 From the Interfaces groupbox, select the interface (ICalendar) that is required for the instance.

e-25

Examples of Presentation Components ActiveX Component

The ActiveX (821) form shows the following definitions:

13 Highlight the interface field and click the Methods button. The Methods (813) form is displayed: 14 Select the method TODAY from the Name listbox.

e-26

Examples of Presentation Components ActiveX Component

The Methods (813) form shows the following definitions:

15 Save and exit all forms and close Form Editor.

Attaching an Event to a Screen Object and Choosing the Component Instance

This component instance is activated automatically when the form is displayed. The instance remains active as long as the form is displayed. Thus, it is not needed to attach it to a screen object and to an event.

e-27

Examples of Presentation Components ActiveX Component

e-28