App Builder Rules Language 2

BluePhoenix AppBuilder 2.1.1 Rules Language Reference Guide BluePhoenix AppBuilder 2.1.1 Rules Language Reference Guide December, 2003 Corporate Headquarters BluePhoenix Solutions Vlierwerf 7B 4704 SB Roosendaal The Netherlands +31 (0) 165 399 401 +31 (0) 165 396 308 fax USA Headquarters BluePhoenix Solutions USA, Inc. 8000 Regency Parkway Cary, NC 27511 United States +1 919.380.5100 +1 919.380.5111 fax www.bluephoenixsolutions.com © 1992-2003 BluePhoenix Solutions All rights reserved. BluePhoenix is a trademark of BluePhoenix Solutions. All other product and company names mentioned herein are for identification purposes only and are the property of, and may be trademarks of, their respective owners. Portions of this product may be covered by U.S. Patent Numbers 5,495,222 and 5,495,610 and various other non-U.S. patents. The software supplied with this document is the property of BluePhoenix Solutions, and is furnished under a license agreement. Neither the software nor this document may be copied or transferred by any means, electronic or mechanical, except as provided in the licensing agreement. BluePhoenix Solutions has made every effort to ensure that the information contained in this document is accurate; however, there are no representations or warranties regarding this information, including warranties of merchantability or fitness for a particular purpose. BluePhoenix Solutions assumes no responsibility for errors or omissions that may occur in this document. The information in this document is subject to change without prior notice and does not represent a commitment by BluePhoenix Solutions or its representatives. TABLE OF CONTENTS Table of Contents AppBuilder 2.1.1 Rules Language Reference Guide 1 Introduction to the Rules Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 What is New in this Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 Rules Language Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 Syntax Flow Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 Syntax Flow Diagram Conventions and Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 Rules Language Statements and Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4 Documentation Conventions and Symbols. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5 2 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1 BOOLEAN Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 Numeric Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 Date and Time Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 Large Object Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6 Object Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7 OBJECT and OBJECT POINTER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 Array Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 Character Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11 CHAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12 VARCHAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13 DBCS and MIXED Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13 Locally-declared CHAR and VARCHAR Data Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14 Variable for the Length of the VARCHAR Data Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15 3 Data Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1 Variable Data Item. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1 Qualifying Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6 Character Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8 Numeric Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11 Symbol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12 Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13 Object Data Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14 i 4 Expressions and Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1 Character Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 Numeric Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3 DATE/TIME Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5 Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6 Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9 Relational Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10 INSET Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11 ISCLEAR Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12 Boolean Condition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13 Comparing Fields with Expression. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13 Comparing Character Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14 Identifying Illegal Comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14 Order of Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15 Comparing Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15 Object Method Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16 Creating a New Object Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16 ObjectSpeak Expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16 ObjectSpeak Conversion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18 5 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1 Numeric Conversion Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2 Mathematical Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2 Date and Time Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5 Date and Time Function Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7 Format String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12 Common Separators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13 Date Format String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14 Time Format String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14 Sample Date and Time Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15 Character String Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17 Double-Byte Character Set Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-21 Variables and Literals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-22 Error-Handling Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-24 HPSError Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-24 Reset Error Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25 Error Message Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25 Support Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25 6 Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1 Local Variable Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 Local Procedure Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4 ii Event Procedure Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6 Using Entities with Equal Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8 Choosing and Setting Signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9 Using System Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11 Controlling Compile Time Subscript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12 Preparing a Rule Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12 Setting Number of Occurrences (Right-Side Subscript) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-14 Setting Number of Occurrences (Left-Side Subscript) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-14 7 Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1 Common Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2 Event Handling Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4 Event Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5 HPS_EVENT_VIEW Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6 Event Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6 8 Control Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1 Comment Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2 ObjectSpeak Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3 File Access Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4 SQL ASIS Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4 START TRANSACTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9 COMMIT TRANSACTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9 ROLLBACK TRANSACTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9 Post Event Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10 Compiler Pragmatic Statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10 PRAGMA KEYWORD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11 9 Assignment Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1 Assignment Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1 Data Type Mapping Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4 Mapping Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-5 CLEAR Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11 OVERLAY Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-12 Using Overlay Statement with VARCHAR Data Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-12 Redefining Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-17 10Condition Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1 IF Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1 CASEOF Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2 Table of Contents iii DO Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-5 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-6 Indexed DO Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-7 DO Statement Restriction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-7 11Transfer Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1 USE Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2 USE RULE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3 USE RULE ... NEST Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5 USE RULE ... DETACH Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5 Passing Data to a Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5 USE RULE ... INIT Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-7 USE COMPONENT Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-9 CONVERSE Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-12 CONVERSE WINDOW Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-13 CONVERSE REPORT Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-13 CONVERSE for Global Eventing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-15 RETURN Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-16 PERFORM Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-17 PROC RETURN Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-19 12Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1 Predefined Macros. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1 Defining Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2 Defining Macros in Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2 Declaring Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3 Abbreviating Rule Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-4 Using Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-4 Macro Substitution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-5 Using Conditional Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-6 Macro Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-6 Using Quoted Strings in Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-7 Changing the Quote Characters in Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-7 Defining Macro Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-8 Using Special Parameters in Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-9 Embedding Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-10 Rescanning with Embedded Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-10 Undefining a Macro. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-11 Using Conditionals in Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-11 Extensions of Macro Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-13 Using Conditional Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-13 Including Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-17 Exiting from Translation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-18 Using Recursion to Implement Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-18 Using String Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-18 Using Arithmetic Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-19 iv . . . . . . . 13-31 PRAGMA AUTOHANDLERS for Java . . . . . . . . . . . . . . . . . . . . 13-6 Specific Considerations for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-12 Creating a New Object Instance for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-14 Local Procedure Declaration in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-44 Table of Contents v . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-41 Size Limitations in COBOL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-18 SQL ASIS Support in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-26 PRAGMA CLASSIMPORT for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4 Subscript Control in C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-23 Data Items in Java . . . . . . . . 13-3 Object Method Call in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-5 Restrictions in Java. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4 Common Procedures in C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-17 Constructing an Event Handler in Java. . 13-38 USE RULE . . . . . . . . 13-36 Assigning Object Data Type Variables in Java. . 13-1 Restrictions in C. . . . . . . . . . 13-42 Functions in ClassicCOBOL . . . . . . . . . . . . . . . . . . 13-18 Transaction Support in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-20 Subscript Control in Java. . . . . . . . . . . . . . . . . . 13-16 Defining Views in Java . . . . . . . . . . . . . . . . . 13-2 Variable for the Length of the VARCHAR Data Item in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-38 CONVERSE REPORT Statements in Java . . . . . . . . . . . . . . . . . . 13-12 Object Method Call in Java . . . . . . . . . . . . . . . . . . 13-13 Functions in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-22 Java Extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-24 Dynamically-Set View Functions . . . . 13-39 Specific Considerations for ClassicCOBOL. . . . . 13-12 ObjectSpeak Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3 Date and Time Functions in C . 13-33 PRAGMA COMMONHANDLER for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-42 OVERLAY Statements in ClassicCOBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-16 Event Procedure Declaration in Java . . . . . .13Platform Support and Target Language Specifics . . . . . . . . . . . . 13-40 Variable for the Length of the VARCHAR Data Item in ClassicCOBOL . . . . . . . 13-34 Static and Static Final Methods and Variables in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3 Comparing Views for C . . . . . . . . . . . . . . . 13-4 Constructing an Event Handler in C. . . 13-35 OVERLAY Statements in Java. . . . . . . . . . . . . . . . 13-4 OVERLAY Statements in C . . . . .. . . . . . . . . . . . . . . . . . . . . . . 13-40 Data Types in ClassicCOBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-23 Additional Functions for Java . . . . . . . . . . . . . . . . . . . . 13-37 CASEOF in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-35 Event Handler Statement in Java . . . . . . . . . . . . . . . . . . . . . . . 13-42 Comparing Views for ClassicCOBOL and OpenCOBOL . . . . . . . 13-7 Comparing Views for Java. . . 13-34 PRAGMA SQLCURSOR for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DETACH OBJECT Statement in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-31 PRAGMA ALIAS PROPERTY for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-7 Java Values and Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-38 Restrictions in ClassicCOBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2 Specific Considerations for C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2 Native Types in Calculator Arithmetic . . . . . B-8 Run-Time Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-5 Truncation Rules for Intermediate Result . . . . . . . . . B-3 COBOL Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . 13-55 PERFORM Statement (PROC) in OpenCOBOL . . . . . 14-2 Command line parameters settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2 Calculator Arithmetic . B-10 vi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-54 Use Rule Statement in OpenCOBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-4 Native Types in COBOL Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-48 Data Types for OpenCOBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-7 \Compatible Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1 INI File Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-4 DMAX Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . 13-56 14Code Generation Parameters and Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-21 A Reserved Words . . . . . . . . . . . . . . . . . . . . . . . 14-9 Processing Order for Parameters . . . . . . . . . . . 13-45 Specific Considerations for OpenCOBOL . . 13-55 Subscript Control in OpenCOBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3 Constant Expressions in Calculator Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Subscript Control in ClassicCOBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-20 Supported Codepages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-49 Views in OpenCOBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1 B Decimal Arithmetic Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-56 Target Language Support Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-45 Restrictions in OpenCOBOL . . . . . . . . . . . . . . . . 13-51 OVERLAY Statements in OpenCOBOL . . . . . . . . . . . . B-1 Platform Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-8 Constant Expression Evaluation in Compatible Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-50 Functions in OpenCOBOL . B-2 Mainframe Platform . . . . . . . . . . . . . . . . . . . . . . . B-1 Native Versus Run-time Support Calculations. . . . . . . . . . . . . . . . . . . . . . . . . . B-6 Overflow Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-48 Variable for the Length of the VARCHAR Data Item in OpenCOBOL . B-7 Constant Expressions in COBOL Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-50 Symbol in OpenCOBOL . . . . . . 13-55 PRAGMA CENTURY for OpenCOBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-56 Release Specific Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2 PC Platform . . . . . . . . . . . . 13-47 OpenCOBOL Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-9 Division by Zero. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-20 Code Generator restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-5 Length and Scale of Function Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1 Code Generation Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-13 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-12 INTEGER and SMALLINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i Table of Contents vii . . . . . . . . . . . . . . . . . . . . . . . . .Error Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-11 Implementation of DIV and MOD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-12 DEC and PIC . . . . . . . . . . . . . . . . . B-13 Overflow Returned . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-11 Mapping to and from Numeric Data Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-12 Expressions . . . . . . . . . . . . . . . . . . . viii . With the Rules Language. specific considerations. and OpenCOBOL language platforms. • Chapter 13. ClassicCOBOL. see Platform Support and Target Language Specifics Topics included in this overview include: • Rules Language Elements • Syntax Flow Diagrams • Rules Language Statements and Arguments Programming knowledge and SQL server database access for coding rules is useful in creating source code with the Rules Language. • Code generation INI settings and parameters are now documented in Chapter 14. and define how the entities comprising an application interact. an application can transfer processing control from one rule to another. This chapter also provides release specific information regarding supported functions. open windows at runtime. ClassicCOBOL. Java. the Rules Language Reference Guide has been reorganized to make platform and release specifics more readily available and to expand the depth of information provided. generate reports. Java. AppBuilder 2. “Code Generation Parameters and Settings”.1 Rules Language Reference Guide This guide contains information on using the AppBuilder Rules Language. Rules Language features platform-specific implementation and is supported on C. • The documentation on reserved words has been improved in Appendix A.1.CHAPTER 1 INTRODUCTION TO THE RULES LANGUAGE AppBuilder 2. For more information about target language specifics.1 Rules Language Reference Guide 1-1 . pass data. to define the processing logic of an application. and extensions for C. What is New in this Book For this release. OpenCOBOL.1. “Platform Support and Target Language Specifics” is a new chapter including restrictions. and functions. “Reserved Words”. syntax. including specific instructions on language usage. a data item is discussed before an expression. the Rules Language elements are listed from the lowest level up. procedures. The Rules Language consists of the statements you use in a rule and the keywords and arguments that comprise them. procedure.that read data from or write data to files This overview describes the elements of the Rules Language from the top level (statement) down to the lowest level (arguments). For instance. throughout this reference documentation.that direct the sequence of events within a Rule • Transfer statements .that describe or explain the Rules code • Assignment statements .that pass control from one Rule to another Rule or to a component. Rules Language statements include: • Declarative statements (declarations) • Procedural statements (procedures) • Comment statements . and an expression before a statement. however. and statements.that move data around within a Rule • Control statements . or invoke windows and reports • File access statements . Thus. Figure 1-1 shows an example of a simple rule syntax diagram with a declaration. 1-2 Introduction to the Rules Language .Rules Language Elements Rules Language Elements A rule is a collection of one or more declarations. Figure 1-1 Sample Rule Diagram declarative_statement procedure statement A rule is analogous to a separate programming routine in a computer language. the documentation describes Rules Language building blocks first and then the statements you use to combine these blocks into Rules. and statement. such as C or COBOL. For whichever line you follow. Follow any one of the possible line paths from left to right. 2. You may follow a loop any number of times. A loop is indicated by an arrow on its left end and appears above another line.Syntax Flow Diagrams Syntax Flow Diagrams The descriptions in this document contain syntax flow diagrams that show how various parts of the Rules Language interrelate and how to use them. Table 1-1 Symbol Flow continues on next line or may include other path AppBuilder 2. Capital letters are used in the syntax diagrams only to indicate Rules Language keywords. Any path that you can traverse from left to right results in valid syntax. Reading a Diagram Follow these steps to interpret the syntax of a diagram: 1. you must use all the words or symbols designated on that line. The conventions used to read the syntax diagrams is described in the sections: • Syntax Flow Diagram Conventions and Symbols • Case Sensitivity • Reading a Diagram • Rules Language Statements and Arguments Syntax Flow Diagram Conventions and Symbols The following conventions and symbols appear in the syntax flow diagrams: Note A syntax flow diagram may not reflect all the conditions and restrictions for a statement. Symbols Used in Syntax Flow Diagrams Meaning Flow of statement starts 3. such as the name of a field or a string literal. Case Sensitivity Rules Language is not case-sensitive. Start at the double-headed arrow on the left side and go to the end of the diagram. • A word in italics is a variable that you provide when coding the statement. • A word not capitalized or italicized is defined in another flow diagram.1 Rules Language Reference Guide 1-3 . You cannot go back to the left unless there is a loop. Rules Language does consider case in a character literal.1. Refer to the text describing each statement for more complete information. • A word in all CAPITAL LETTERS is a Rules Language keyword. a character value. all of the following are possible ways a variable data item can appear according to the following diagram: • field_name • field_name OF view(5) • field_name OF view OF view field_name OF view ( object_name index ) . by an argument. a boolean value. The actual argument for each clause varies by statement.Syntax Flow Diagrams Table 1-1 Symbol Symbols Used in Syntax Flow Diagrams (Continued) Meaning Flow continued from previous line Flow may branch in either direction Flow of statement ends For example. an argument can always be described as one of the following: • A data item . However.data items. AND. object_reference property_name Rules Language Statements and Arguments Each Rules Language statement consists of one or more clauses. in most cases.expressions linked with relational operators (such as = or >) and other conditions linked with Boolean operators (such as OR. other expressions.an argument only for an SQL ASIS statement • Another statement or the name of a specific entity (such as a window or report) 1-4 Introduction to the Rules Language . or a symbol) or a variable (a view or a field) • An expression . and NOT) • An SQL statement .either a constant (a numeric value. A clause is a Rules Language keyword followed. . and functions (such as ROUND or STRLEN) linked with operators (such as + or -) • A condition . ELSE... For example: IF condition statement ELSE statement ENDIF appears in text as: IF.Syntax Flow Diagrams Documentation Conventions and Symbols When discussing a statement within text.1.1 Rules Language Reference Guide 1-5 .ENDIF. CLEAR variable_data_item appears simply as: CLEAR. In addition. its arguments are generally replaced by ellipses. a keyword appears in all CAPITAL letters... or dropped if they trail the statement. AppBuilder 2. Syntax Flow Diagrams 1-6 Introduction to the Rules Language . For ClassicCOBOL specific information see: Data Types in ClassicCOBOL. See “Declarations”for more information. Data Type Syntax boolean_data_type numeric_data_type date_and_time_data_type large_object_data_type object_data_type character_data_type Data Types The data types in the Rules Language are: • BOOLEAN Data Type • Numeric Data Types • Date and Time Data Types • Large Object Data Types • Object Data Types • Character Data Types: For C specific information see: Variable for the Length of the VARCHAR Data Item in C. The data type of a data item determines both its compatibility with other data items and how the data item is stored or displayed. For OpenCOBOL specific information see: Data Types for OpenCOBOL AppBuilder 2. Declare a data item as having a certain data type either locally using the DCL statement or as a property of a field.1.1.1 Rules Language Reference Guide A Rules Language data item is defined to be of a specific data type.CHAPTER 2 DATA TYPES AppBuilder 2.1 Rules Language Reference Guide 2-1 . For Java specific information see: Java Values and Conversions. and cannot have any decimal point if it is an INTEGER or SMALLINT data type 2-2 Data Types . j INTEGER.Using the Boolean Data Type DCL b BOOLEAN. <* ELSE MAP 1 TO i *> This line is not. <* ENDIF Numeric Data Types There are four numeric data types: • SMALLINT • INTEGER • PIC • DEC A data item of one of these types: • Cannot contain a non-numeric character • Can only have a negative sign or no sign in front of the expression (no sign indicates a positive number) • Can only have one decimal point if it is a PIC or DEC data type. BOOLEAN Syntax identifier BOOLEAN Example . ENDDCL MAP 1 TO i MAP 2 TO j MAP i > j TO b *> False <* MAP TRUE TO b IF b or FALSE MAP 10 TO i *> This line is executed. Variables of this type can be used anywhere in place of a condition in a rule and results of conditional expressions can be mapped to these variables.BOOLEAN Data Type BOOLEAN Data Type The BOOLEAN data type can be either of two values: TRUE or FALSE (which are reserved words by default). i. 647 inclusive.Numeric Data Types Numeric Data Syntax SMALLINT INTEGER PIC ' S DEC 9 ( integer_literal . INTEGER Use INTEGER for a four-byte integer data item that contains values between –2. PIC Use PIC primarily for data items in two situations. a DEC data item is stored packed two bytes to one. • A PIC data item is the only numeric data type that can be compared to a character data type. an unsigned integer picture can be assigned to the following types of fields: • any signed/unsigned numeric data type • CHAR • VARCHAR • TEXT • IMAGE AppBuilder 2. • On the host.648 and 2.767 inclusive.1 Rules Language Reference Guide 2-3 .483.483.147. An unsigned integer picture can be compared to the following: • any signed/unsigned numeric data type • CHAR • VARCHAR • TEXT • IMAGE In addition.147.768 and 32. integer_literal V 9 ) 9 ' SMALLINT Use SMALLINT for a two-byte integer data item that contains values between –32. a PIC type is not.1. no byte is reserved for it. display.2) appears as xxx.Numeric Data Types An unsigned integer picture can be concatenated with the following: • an unsigned integer picture • CHAR • VARCHAR • TEXT • IMAGE Declaring a data item as PIC creates a storage picture that formats numeric data according to a sequence of codes with the meanings shown below. A DEC data item always has a byte reserved for a sign and is packed two bytes to one on the host. which is calculated from the difference between the length and the scale A data item declared as DEC (5. the second integer value is the scale (the number of places to the right of the decimal point). Also. or edit PICTURE. An unsigned integer picture can be concatenated with DBCS and MIXED. Table 2-1 Code S 9 V PIC Data Item Codes Meaning Signed number Number placeholder Decimal placeholder Note A PIC declaration represents an internal or storage PICTURE and should not be confused with an external. If no sign is declared. For example. See Release Specific Considerations for more information. the following restrictions apply to a picture string: • It should contain no more than thirty-one (31) 9s • It cannot contain any embedded spaces For releases that support DBCS. an unsigned integer picture can be assigned to a MIXED field.xx. DEC Use DEC for a decimal data item. ClassicCOBOL.99. in Java. and less than or equal to length (0 ≤ scale ≤ length) • Length must be greater than or equal to 1 (one) and less than or equal to 31 (thirty-one) (1 ≤ length ≤ 31) • Length includes the scale.99 to 999. a PIC data item declared with the storage picture S999V99 can contain numeric data from –999. Besides the syntax shown in the flow diagram. 2-4 Data Types . but not the decimal point. The first integer value after a DEC keyword is the length of the data item. The following restrictions apply to scale and length: • Scale must be greater than or equal to 0 (zero). The scale equals 0 (zero) if no scale value is provided. you cannot write S9(3)V9(2) or S(3)9V(2)9 as in COBOL or PL/I. and OpenCOBOL. 15. Date and Time Syntax DATE TIME TIMESTAMP For OpenCOBOL considerations regarding Date and Time Syntax. For OpenCOBOL considerations regarding DDL.1.11. Date and Time Data Types A data item declared as one of the following three data types must contain numeric data: • DATE and TIME • TIMESTAMP Caution The format standards used for date and time data types are set during installation. the delimiter designated in your language configuration file must match the delimiter used by your database or your rule will not prepare.05 2:15 PM 14.yyyy yyyy-mm-dd Any site-defined form Example 1996-11-30 11/30/1996 30.mm. For ClassicCOBOL specifics including decimal field representation and DDL.ss hh:mm:ss Any site-defined form Example 14.1996 1996-11-30 Time Format hh. see Using DEC with OpenCOBOL.05 14:15:05 AppBuilder 2. see Date and Time Functions in OpenCOBOL. see Decimal Field Representation in ClassicCOBOL.1 Rules Language Reference Guide 2-5 .mm.15. The specific standard designated for your system is contained in a configuration file. For instance.mm.ss hh:mm AM or PM hh. Date and Time Formats AppBuilder supports the standard date and time formats shown in Table 2-2: Table 2-2 Standard ISO (International Standards Organization) USA EUR (European) JIS (Japanese Industrial Standard Christian Era) LOCAL (site defined) Standard Date and Time Formats Date Format yyyy-mm-dd mm/dd/yyyy dd.Date and Time Data Types See “Local Variable Declaration” for more examples of locally declared data items that use a numeric data type. The format for your system must match the format your database uses or errors occur. a reference is the fully-qualified path and file name of the large-object file. Locally-declared Dates and Times See “Local Variable Declaration” for examples of locally-declared data items that use the date and time data types. a reference is a generated name. or generated explicitly by the HPS_BLOB_GENNAME_FILE system component. but the actual units used are system-dependent and are determined by the limitations of the operating system.Large Object Data Types DATE and TIME Use DATE for a date data item. For OpenCOBOL considerations regarding TIMESTAMP. either generated automatically by AppBuilder when a large-object file is transferred to the host. has a date number of 1. you cannot query them from an SQL server database with a finer time measurement than minutes due to an SQL server restriction. The value in the data item is the number of days past the date of origin. AppBuilder processes TEXT and IMAGE data items like CHAR (256) data items. It consists of three independent subfields: <DATE>:<TIME>:<FRACTION> The <DATE> and <TIME> parts are for the DATE and TIME data types. The TIME data type has a length of four bytes. <FRACTION> is platformdependent and provides a finer time measurement than the <TIME> subfield. The value in the FRACTION field is usually picoseconds. A date variable has a length of four(4) bytes. On the host. On the workstation. 2-6 Data Types . Large Object Data Types Use a data item of the TEXT or IMAGE data type to hold a reference to a file containing a large object. Use TIME for a time data item. TIMESTAMP Use TIMESTAMP for a time data item where you need greater precision than milliseconds. so any conditions that apply to CHAR data items also apply to TEXT and IMAGE data items. For OpenCOBOL considerations regarding DATE. January 1. Caution Although you can set the values for TIME and TIMESTAMP to contain seconds and milliseconds. The value in the data item is the number of milliseconds past midnight. 0000. The TIMESTAMP data type has a length of 12 bytes. see Using Date and Time with OpenCOBOL. see Using Date and Time with OpenCOBOL. Converting Dates and Times You can use the date and time conversion functions discussed in Functions to convert a variable from one date and time data type to another (or to an integer or character data type). You can also map a TEXT or IMAGE data item to another TEXT or IMAGE data item. AppBuilder automatically transfers the file to the workstation when the host rule returns control to the workstation rule. The large-object file itself is not copied. Transferring Large-Object File from Workstation to Host To transfer a large-object file from a workstation to a host. Note When you map a TEXT or IMAGE data item to another TEXT or IMAGE data item. only the large-object file name is copied.1. • When a workstation rule uses a host rule. Object Data Types OBJECT data types include: • OBJECT Type • Using Object Pointer in Java • Array Object AppBuilder 2. This makes the name available to the workstation rule—which can then pass it back to a host rule and request that the rule transfer the file. map the full path and file name of the large-object file to a TEXT or IMAGE field in the input view of a host rule.Object Data Types Large Object Syntax TEXT IMAGE TEXT Use TEXT for a data item that holds a reference to a text large-object file. AppBuilder automatically transfers the large-object file to the host. if the host rule maps the name of a large-object file to a TEXT or IMAGE field in its output view. then copy the name from the TEXT or IMAGE field of the host rule’s input view to a TEXT or IMAGE field in the host rule’s output view. Mapping Character Values to TEXT or IMAGE You can assign a character value to a TEXT or IMAGE data item using a MAP operation.1 Rules Language Reference Guide 2-7 . do the following: • In the workstation rule. • If you want to later transfer the same large-object file. IMAGE Use IMAGE for a data item that holds a reference to a binary large-object file (BLOB). AppBuilder overwrites the TEXT or IMAGE field with the name of the large-object file on the host. • When the workstation rule uses the host rule. or to a character field. The only exception is the listener name in the LISTENER clause in an event or error handler declaration.The group to which this object belongs The following subsystems are supported: • GUI_KERNEL . • subsystem .a string that identifies the implementation of the class. Note Refer to the ObjectSpeak Reference for more information on using objects and AppBuilder-supplied objects. Therefore. Refer to OBJECT and OBJECT POINTER in Java for more details.The numeric. character. it might be the full Java class name for Java classes. Array Object Use the array object (OBJECT ARRAY form) to declare an array as a locally-declared data item. any identifier with apostrophes is case-sensitive. Case-sensitivity in Identifiers Generally speaking.the set of AppBuilder-supplied window controls • JAVABEANS . date/time and boolean and object (with certain limitations. they are deprecated for C. Not case-sensitive. 2-8 Data Types . The identification string is case-sensitive. any identifier without apostrophes is not case-sensitive.used for any Java class • type . • class_name .Object Data Types Object Data Type Declarations identifier OBJECT TYPE POINTER TO ‘ class_identifier ‘ class_name OF subsystem ARRAY OF type where: • class_identifier . likewise.Class name to be used in a rule. OBJECT and OBJECT POINTER OBJECT and OBJECT POITNER are supported only for Java. See “Event Procedure Declaration” for the syntax used in this declaration. see Array Object for more details). 1 Rules Language Reference Guide 2-9 . Note: You can only have an array of non-typed objects.method(index) Where array_name is the overall name of the array.e. Array Methods The following methods can be applied to arrays: • Append • Size • Elem • Insert • Delete AppBuilder 2. the method following the delimiting period specifies a particular operation. See “Date and Time Data Types”. for example: DCL array1 OBJECT ARRAY OF INTEGER. An array reference operation takes the form: array_name.1. OBJECT ARRAY OF OBJECT See “BOOLEAN Data Type” boolean_data_type A variable declared locally in a DCL statement is not contained in the repository and is not available to any rules or components the declaring rule uses in the way that views and fields are. and the value resulting from the evaluation of index specifies a particular member of the array.Object Data Types OBJECT ARRAY Syntax arrayname OBJECT ARRAY OF character_data_type numeric_data_type date_and_time_data_type object boolean_data_type where: character_data_type date_and_time_data_type numeric_data_type object See “Character Data Types”. i. See “Numeric Data Types”. array2 OBJECT ARRAY OF CHAR. See “OBJECT and OBJECT POINTER”. Its index is equal to the size of the array. When first declared. If it is used to get the value of an array element.elem(i+2) TO dec_value After this statement is executed. For example: MAP array1. it also must have one parameter. and the second argument’s value is assigned to the array element with the specified index.elem(123) After this statement is executed. then it has one argument. an array has a size of zero. then the first argument must be the index. If the elem method has two arguments. The default conversions are: • integer to smallint • integer to dec • smallint to integer • smallint to dec • dec to smallint • dec to integer • char to varchar • varchar to char • dbcs to mixed • char to mixed • varchar to mixed • mixed to char This method appends one element at the end of an array. Size This method takes no arguments and returns the size of the array. If this method is used as a destination in a MAP statement.Object Data Types Append This method takes one argument that must be of the same type as the array’s type. The size of an array is determined dynamically by how many elements you map to the array. field dec_value contains the same value as the array element with index i+2. Elem This method could have one or two arguments. the element index: MAP char_value TO array2. the element index. the array element with index 123 contains the same value as the field char_value. 2-10 Data Types . or it could be converted to this type. the index value must be within the range from 1 to the size of the array. Otherwise. the array element with index 123 contains the same value as the field char_value.1 Rules Language Reference Guide 2-11 . a runtime error occurs. Character Data Types Character data types hold character data.elem(123. Delete This function has only one argument. Otherwise. the index of an existing element. char_value) This statement has the same effect as the previous MAP statement. After the specified element is deleted.Character Data Types For example: array2. a run-time error occurs. all element indices following the deleted element decrement by 1.1. Note In all cases. Insert This method has two arguments: the index and a value. Note In all cases. the index value must be within the range from 1 to the size of array + 1. The character data types in the Rules Language are: • CHAR • VARCHAR • DBCS and MIXED Data Types Other topics include: • Locally-declared CHAR and VARCHAR Data Items • Variable for the Length of the VARCHAR Data Item Character Data Syntax CHAR VARCHAR DBCS MIXED ( integer_literal ) AppBuilder 2. A new array element consisting of the value is inserted into the array in the sequential location specified by the index and all the element indices thereafter are incremented by 1. that is. A CHAR data item can have a maximum length of 32K bytes in local declarations. No specific validation is performed on the content. it is still relevant for data entering or exiting such an environment as is the case for JNetE marshalling. validation at runtime. at least. it loses any special behavior or validation that may have been previously applied to it. CHAR fields contain single-byte character data. Once such data is in a CHAR field. For this reason. while there is no distinction between single-byte and double-byte characters. Also. CHAR Use CHAR for a fixed-length character data item. it still applies for data entering or exiting such an environment as is the case for JNeteE marshalling. a conversion function must be explicitly specified. The only exception is a DBCS literal which can be mapped directly to a CHAR field. The single-bye space character is the standard ASCII space character or Unicode \u0020. Even codepages for the same language may be double-byte on one platform but not another. A field will be padded to the specified maximum length with single-byte spaces. Field sizes are specified in characters but are allocated on the underlying assumption that one character equals two bytes. within a Unicode environment like Java.Character Data Types Definitions Single-byte Single-byte characters occupy one byte in the current default or specified codepage. Field sizes are specified in characters but are allocated on the underlying assumption that one character equals one byte. Double-byte Double-byte characters occupy two bytes in the current default or a specified codepage. Within a Unicode environment such as Java. except in environments that have a specific type for such data such as a mainframe ‘graphic’ type. This means that CHAR data item is always padded with spaces to its declared length. (A fixed-length field reserves and retains the number of bytes you define in the field’s length property. The double-byte space character is the ideographic or wide space Unicode character \u3000. It is assumed that this codepage will generally be that of the eventual destination platform for such data. 2-12 Data Types . Applying different validation rules for specific fields because they are not sent to the primary backend system is not a realistic option. It should also be noted that the concept of double-byte is dependent on the codepage. Rules Language statements will be validated to the extent that when mapping non-CHAR fields or literals to a CHAR field. while this single-byte concept is essentially meaningless.) The length of a CHAR data item is calculated in characters (or bytes). Trimming the field will remove any trailing single-byte spaces. a data item has a length of 1 if no integer follows CHAR. CHAR (n) denotes a CHAR data item of length n. It is also expected that the specified codepage may have to be a compromise because we must treat all DBCS fields similarly. needs to be performed in the context of a specified codepage. thus it essentially becomes single-byte data. See “Variables and Literals” for more information about COBOL’s use of VARCHAR in determining the length of a data item. Field size is defined in terms of double-byte characters. a data item that uses the standard ASCII or EBCDIC character set—256 distinct characters encoded using one byte of information). thus expanding the data. VARCHAR (n) denotes a VARCHAR data item of maximum length n. even though the field’s data may not occupy the maximum length. When mapping to. See CHAR for more specifics about mapping double-byte characters. A data item’s length is calculated in characters (or double bytes) and can have a maximum length of 16K.Character Data Types VARCHAR Use VARCHAR for a variable-length character data item. A VARCHAR data item can have a maximum length of 32K bytes. Such length validation must occur in the context of a specified codepage. some languages use different character sets because they have more than 256 distinct characters. AppBuilder 2. VARCHAR is treated the same as CHAR except that no padding beyond that already in the source field will be added to the value. rather than codepage converted lengths. Warning Only the DBCS enabled versions of AppBuilder support DBCS and MIXED data types. or constructing new DBCS fields. unless the source is another DBCS field. User input fields are validated for length to ensure no truncation of non-space data occurs when undergoing codepage conversion. and stateful codepages for DBCS regions where characters or escape sequences are embedded in the data to switch modes. AppBuilder contains two double-byte character set data types DBCS and MIXED.) The length of a VARCHAR data item is calculated in characters (or bytes). For those languages. This is based on actual field lengths. a data item has a length of 1 if no integer follows VARCHAR. See the chapter on DBCS Programing in the Developing Applications Guide for more details. the source data is validated for content to verify that all characters are double-byte. and should typically be the one which is used by JNetE when marshalling data for transmission to backend systems. This is done in order to handle conversions from Unicode to other codepages. and thus in byte terms it is twice the number of characters.1. The source data is truncated if it is too long to fit in the destination field. Using these data types in other versions of AppBuilder causes the code generation step of the preparation process to fail.1 Rules Language Reference Guide 2-13 . such as when marshalled by JNetE. (A variable-length data item initially reserves the number of bytes defined in the length property. DBCS Data type DBCS can contain only fixed-length. DBCS and MIXED Data Types You can use a CHAR and VARCHAR data type only with a single-byte character set (SBCS) data item (that is. VARCHAR fields contain single-byte character data. Validating that characters are double-byte will be determined in the context of a specified codepage. double-byte character set data items. However. This leads to different behavior for such platforms. Such length validation must occur in the context of a specified codepage which is typically the one used by JNetE when marshalling data for transmission to backend systems. a varied number of characters can fit into a particular MIXED field. rather than on codepage converted lengths. this limitation on double-byte characters is not present. and can have a maximum length of 32K.Character Data Types Data is padded to specified maximum length with double-byte spaces. Thus. the number of double-byte characters that may be stored in such a field is a maximum of half the field’s specified size. not in bytes. Keep the following in mind when writing multi-platform applications: • DBCS and MIXED Data Types in Java • Variable for the Length of the VARCHAR Data Item in C • DBCS and MIXED Data Types in COBOL for ClassicCOBOL and OpenCOBOL. All string functions with MIXED arguments work in characters. MIXED Data type MIXED can contain double-byte characters. single-byte characters. or any combination thereof. To minimize such issues. This is based on actual field lengths. Field size is defined in terms of single-byte data. This is done in order to handle conversions from Unicode to other codepages. If such truncation causes the second byte of a double-byte character to be truncated. the MIXED variable declaration is the only place where its storage length is specified in bytes. Locally-declared CHAR and VARCHAR Data Items See “Local Variable Declaration” for examples of locally-declared data items that use CHAR and VARCHAR. A field is padded to it’s specified maximum length with single-byte spaces. such as Java. thus expanding the data. A MIXED data item’s length is calculated in bytes in C and COBOL and in characters in Java. whether double-byte or single-bytes. 2-14 Data Types . for usability purposes. Trimming data will remove any trailing double-byte spaces. When mapping to or constructing a new field of this type. the source data is truncated if it is too long to fit in the destination field. user input fields are validated for length as specified below. Trimming the field removes any trailing single-byte or double-byte spaces. Note that for Unicode based platforms. such as when marshalled by JNetE. Note Because of the differences in character representation on different platforms. the whole of the double-byte character is truncated and the field padded is as necessary. User input data is validated for length to ensure no truncation of non-space characters occurs when undergoing codepage conversion. and stateful codepages for DBCS regions where characters or escape sequences are embedded in the data to switch modes. However. a variable named VC of type VARCHAR declares the variable: VC_LEN of type SMALLINT. this field contains the actual length of the corresponding VARCHAR variable unless it has been changed directly. A dynamic variable can be changed directly through an assignment statement and these changes are reflected in the VARCHAR contents.Character Data Types Variable for the Length of the VARCHAR Data Item Any variable of type VARCHAR implicitly declares a variable of type SMALLINT named: <varchar variable name>_LEN For example. The _LEN variable is a dynamic variable that represents the length of the VARCHAR variable.1 Rules Language Reference Guide 2-15 . the semantics of _LEN (the way a change to _LEN effects the corresponding VARCHAR data) varies on different platforms. Complete descriptions of the variations by platform are provided in the following sections: • Variable for the Length of the VARCHAR Data Item in C • Variable for the Length of the VARCHAR Data Item in Java • Variable for the Length of the VARCHAR Data Item in ClassicCOBOL • Variable for the Length of the VARCHAR Data Item in OpenCOBOL AppBuilder 2.1. At any given time. However. Character Data Types 2-16 Data Types . 1. AppBuilder 2. Views and fields are considered variables because rules can change the data in them.1 Rules Language Reference Guide 3-1 . Table 3-1 Classification of Data Items Variable Data Item X X X X X X X Constant Data Item Data Item Name View Field Symbol Literal Array Default Object Alias Variable Data Item A rule can use any view or field in its data universe as a variable data item.1.CHAPTER 3 • View DATA ITEMS AppBuilder 2.1 Rules Language Reference Guide A data item is a container for data that a rule processes. are considered constants. whose values can be changed only by editing the rule’s code or altering a value entity in the repository. Literals and symbols. Data items described in this section include: • Variable Data Item • Character Value • Numeric Value • Symbol • Initialization • Object Data Items Table 3-1 shows how the various data items are classified. See “Local Variable Declaration” for how to declare a variable locally. You can either define a variable to your repository to be used globally or declare it within a rule to be used locally within that rule. where index_list is: object_speak_reference . ( expression ) where object_name is: • The system identifier (HPSID) of the object • The alias of the object (see “Object Data Items”) • An object (see “Object Data Types”) • An array (see “Array Object”) 3-2 Data Items .Variable Data Item Generally. you can transfer data from all the fields of one view directly to all the fields of another view by mapping the first view to the second. ( index ) object_name . numeric_expression where: Index numeric expression where object_speak_reference is: . Variable Data Syntax field_name ( index_list ) OF-view view . For instance. a view can be a variable data item almost everywhere a field can be. ( index ) field_name view . property_name . exceptions are noted where they apply. Variable Data Item expression numeric_expression view See “Expression Syntax”.B.C is exactly and fully included in the path A. ambiguity error can be issued during rule preparation. In such a case. Ambiguity in rule data hierarchy is not checked until rule is prepared. a given field or view can appear more than once in a rule’s data universe.” and the name of a field after it. See “Numeric Expressions”. because A.X A. See “View”.1 Rules Language Reference Guide 3-3 .X are not.C. referring to just the name of a field or view could lead to an identification conflict or confusion.B. qualify potentially ambiguous references with some or all of the names of the variable’s ancestor views. To avoid this.X.C. To uniquely identify different instances of a field or view.B. Qualifying Fields When you reuse an entity defined in the repository.B.C. When view was used as a top level view and as a child of another view View hierarchy is ambiguous for the view X if there are two occurrences of the view X and full path to the one of the occurrence is exactly and fully beginning of the path to the second occurrence.B. place the name of a containing view before “.C.D. Thus. AppBuilder 2. Such an error is usually reported with BINDFILE prefix in the error message and is issued in two cases: 1.X are ambiguous. But in this hierarchy A.D. For example. 2.1. There are two ways to uniquely qualify fields: using either “.D.X A. consider the following hierarchy: The following qualifications: A.B.” or the OF clause. CUSTOMER. that information also appears in two other instances of EMP_DATA (assuming that EMP_DATA under EMP_UPDATE is an input/ output view. This type of fields and views qualification differs in order (direction): the sequence begins from innermost item (field or view) for OF clause. For example. Add the name of an ancestral view in an OF clause following the name of the variable. <* 3-4 Data Items . Examples of Field Qualifications and Using Subscripts Example of Field Qualifications *LAST_NAME OF CUSTOMER OF ALL_CUSTOMERS LAST_NAME OF ALL_CUSTOMERS *> Using the dot symbol<* ALL_CUSTOMERS.LAST_NAME ALL_CUSTOMERS. in the hierarchy shown above. They each refer to the same fields and are completely equal in rights. 10) *> . You do not have to give the entire list of ancestor or successor views if a partial list uniquely identifies the intended view or field. A root view is a view whose parent is not another view. and from the outermost item if you use the “. Example of Using Subscripts *> OF clause <* LAST_NAME OF CUSTOMER OF ALL_CUSTOMERS OF DEPARTMENT(5.” operator. the ancestor list must contain the name of at least one view that uniquely identifies the intended view or field. (See “Data Universe” topic in the Developing Applications Guide. and not a work view). The AppBuilder environment considers all root views with the same name in a rule’s data universe to be the same view. Warning Be careful when reusing views.) Mapping information to one such view maps the information to all root views with the same name in the rule’s data universe. To be sufficient. . if you map information to EMP_DATA of the rule EMPLOY.Variable Data Item Using the OF clause produces the same result.LAST_NAME The following examples illustrate the use of subscripts (indexes). Both of the following examples can be used to qualify fields. even if the names are fully qualified. (10).Variable Data Item DEPARTMENT. the following is not correct: DEPARTMENT.LAST_NAME You can write: LAST_NAME OF ALL_CUSTOMERS(5. and the employee’s supervisor’s name. the following MAP statement defines the unique identity of: the employee’s LAST_NAME field: MAP 'Attonasio' TO LAST_NAME OF NAME OF EMP_NAME OF EMPLOYEE or the customer’s: MAP 'Borges' TO LAST_NAME OF NAME OF CUSTOMER OF RESERVATION_LOG OF EMPLOYEE or the supervisor’s: MAP 'Calvino' TO LAST_NAME OF NAME OF SUPERVISOR OF EMPLOYEE AppBuilder 2.ALL_CUSTOMERS(2).CUSTOMER(10).LAST_NAME Using Partial Qualification In the sample view in Figure 3-1. For example. 10) You can omit intermediate views that are not ambiguous. the employee’s customer’s name. the subview NAME is used in three places to hold three categories of data: the employee’s name.1 Rules Language Reference Guide 3-5 .1. (2). You cannot omit views that require indexes when using the dot notation to qualify fields. Figure 3-1 Sample View Hierarchy The following example shows a method of specifying the unique data contained in each field by qualifying a part of an argument based on a unique identifier that precedes the field. 10) LAST_NAME(5. For a fully-qualified statement. since each field has at least one unique ancestor. and only one in SUPERVISOR. only one in CUSTOMER or RESERVATION_LOG. the view EMP_NAME exists solely to distinguish its instance of the NAME view from the other two. Essentially. can be shortened. it is a “container” for other views and fields.View These qualifications. Note For detailed information about the Information Model. refer to the Information Model Reference Guide. View Name Syntax view_name ( index_list ) OF-view_name view_name . see Comparing Views for ClassicCOBOL and OpenCOBOL. View A view is an object in the Information Model that defines a data structure you use within your rules. Thus. In fact. numeric_expression where: Index numeric_expression For specific considerations for OpenCOBOL. the three last-name fields could be identified as: LAST_NAME OF EMP_NAME LAST_NAME OF CUSTOMER (or LAST_NAME OF RESERVATION_LOG) LAST_NAME OF SUPERVISOR One instance identifies the LAST_NAME field in EMP_NAME. however. ( index ) where index_list is: . 3-6 Data Items . ( index ) view_name ( index_list ) view_name . For specific considerations for ClassicCOBOL. see Views in OpenCOBOL. however. Example . You can nest arrays up to a maximum of three levels. However. some platforms or compilers may have such limitation. even if the view’s name does not appear. with the same field data types. Size Limitations AppBuilder has no limitations on the view size.View Usage When you use a view in a Rules Language statement. Using the Occurs Property The Occurs property works with the View includes View relationship only. each of which can be accessed separately by any rule that has the DEPARTMENT view in its data universe. you may omit the names of some of a field’s ancestral views in a statement. The following statements reference the twelfth employee’s last name in Department 4: MAP 'Jones' TO LAST_NAME OF DEPARTMENT OF SITE (4. place the occurrence number of the multiply-occurring view in parentheses after the last qualifier. To reference an individual occurrence of a field in a multiple-occurring view. Caution As discussed in “Variable Data Item”. Note While the view names go up the hierarchy when read from left to right. The following statements reference the twelfth occurrence of the employee view: MAP 'Jones' TO LAST_NAME OF EMPLOYEE OF DEPARTMENT(12) or MAP 'Jones' TO DEPARTMENT. list the indices of its parent views in parentheses after the last qualifier.LAST_NAME Assume a SITE view includes the DEPARTMENT view mentioned above. Each “row” is simply an indexed instance of the child view. each DEPARTMENT view has 20 EMPLOYEE views. you need only provide the name of the view as defined to the repository. you must place the subscripts in reverse order so that they go down the hierarchy when read from left to right. and EMPLOYEE view contains a field LAST_NAME. For specific considerations for ClassicCOBOL and OpenCOBOL.1 Rules Language Reference Guide 3-7 . However. A non-integer number is truncated.Using the Occurs Property to Set the View Assume the relationship between a view named DEPARTMENT and its subview named EMPLOYEE has an Occurs property of 20.EMPLOYEE(12). This forms what other programming languages call an array. see Size Limitations in COBOL. You can refer by number to a specific instance of a multiple-occurring subview within the rule that owns the including view. you can emulate multidimensional data structures by repeating a given view structure under another view. To refer to a particular element.12) or AppBuilder 2. you must always include the occurrence number of a multiple-occurring subview in a statement. This index can be any expression that resolves to a number. This means that neither fields nor top-level views can be subscripted. and the DEPARTMENT view is itself occurring. You define a multiple-occurring subview by changing the Occurs times property in the View includes View relationship that connects the child view to its parent.1. Thus. See “Using Character Literals. 3-8 Data Items . Two consecutive single quotes with no text between them represent the null string.DEPARTMENT(4). A character literal is a string of up to fifty(50) characters enclosed in single or double quotes. Character Value Syntax symbol ' " string_literal string_literal ' " character_field where: character_field symbol Usage You can include a single-quote character ( ' ) as part of a character string by putting two single quotes (not a double quote) in its place in the string. or a character literal. Character Value A character value can be a symbol associated with a character value. Use caution with regard to the fields because they can be unqualified in Rules code.Character Values The following is an example of a string literal in a MAP statement: MAP 'This is a character literal' TO MESSAGE The MAP statement a variable data item of any character type See “Symbol”. you must include the subscript for this view.LAST_NAME Note Even though the name of the EMPLOYEE view does not appear in the statement. which is the value of a blank character field. statements like the following can be confused for subscripted fields: MAP 'Jones' TO LAST_NAME(12) The subscript here does not refer to the LAST_NAME field. and Octal Notation” for more on the use of quotation marks in string literals.Character Value MAP 'Jones' TO SITE. but to the omitted EMPLOYEE view.EMPLOYEE(12). Example . a field of a character data type. A string literal is a constant. Hexadecimal. Using Character Literals. it is considered a MIXED literal. Character literals can be placed on one or more lines of Rules Language code. If a literal begins with a single quote.' 'Preston Sturges.1 Rules Language Reference Guide 3-9 . For example: MAP 'Orson Welles." TO director_list Single-Quote Literals Single-quote literals are strings of characters. If such a literal contains only DBCS characters. see the example under Symbol. The supported escape sequences are listed in Table 3-2.' TO director_list or MAP "Orson Welles. These escape sequences allow you to use a sequence of characters to represent special characters. Escape sequences also allow you to specify characters with hexadecimal or octal notation. then it must end with a single quote. If a literal begins with double quotes." "Preston Sturges. put quotation marks at the end of the first line and begin the second line with the same quotation mark. it must also end with a double quote. and Octal Notation Character literals can be enclosed in double or single quotes. The following statement tests for an empty value in a character field: IF NAME = '' For a symbol associated with a character value. To place the literal on several source code lines. including nonprinting characters. it is considered a DBCS literal.Character Value MAP 'Enter the items’s price' TO MESSAGE puts the string “Enter the item’s price” in the MESSAGE field.' 'Frank Capra. AppBuilder 2." "Frank Capra. You can include the single-quote character itself (') as a part of single-quote literal by putting two single quotes (not a double quote) in its place in the string: MAP 'Enter the item"s price' TO message Double-Quote Literals Double-quote literals can contain escape sequences beginning with the backslash (\).1. DBCS and MIXED Literals Both single-quote and double-quote literals can contain DBCS characters. If a literal contains both DBCS and SBCS characters. Hexadecimal. and a binary equivalent of 00010000? No. Therefore. the code generation process establishes the end of the hex or octal number when it encounters the first non-hex or non-octal character correspondingly. leading zeros are ignored.. Each hex or octal number represents only one character. you should use the following string literal: "\x11\x10". "\x0cDebug" will have only three characters first. Using Hexadecimal and Octal Notation The backslash starts an escape sequence and is valid only in literals within double quotes... the character value is equal to the remainder of integer division of this number by 256. consider these examples: First. During preparation. You could also say that only the last byte is used.Character Value Table 3-2 Supported Escape Sequences Character Name Alert (Bell) Backspace Form feed New-line Carriage return Horizontal tab Vertical tab Question mark Single quote Double quote Backslash octal number hex number Escape Sequence \a \b \f \n \r \t \v \? \' \" \\ \o. \xEB and "ug". Second: "\x1110"— Does this equate to two bytes which have a hex value of 1110. and a decimal equivalent of 4368. For example. In the discussion about hexadecimal and octal notation representing only a single character and the integer division. This is converted to two bytes.. Note that hex or octal number ends with the first non-hex or non-octal character only. "/x10"— Does this equate to a byte which has a hex value of 10.h Note that for characters notated in hexadecimal. and binary value 00010000. and a binary equivalent of 0001000100010000? "\x1110" is converted to one byte. If you would like to define two bytes. hex value 10. and a decimal equivalent of 16. if an octal or hex number is greater than 255. Its decimal value is 16 (which is the reminder of integer division 4368 by 256). Not "/x10". but "\x10" has a decimal value 16. 3-10 Data Items .o \xh. the first with decimal value 17 and the second with decimal value 16. and this is converted to one byte. Hexadecimal. The integer and fraction part of the literal are separated by a period.1 Rules Language Reference Guide 3-11 . Numeric Value Syntax symbol numeric_literal integer_field smallint_field decimal_field picture_field where: symbol integer_field smallint_field decimal_field picture_field Usage An integer literal must be within the range specified for the data type. the following literals are all equal: • 255 • 0xff • 0Xff • 0x0ff • 0XFF • 0x00FF See “Using Character Literals.Numeric Value Numeric Value A numeric value can be a symbol associated with a numeric value. a field of a numeric data type. and. Integer numbers as well as decimal numbers can be represented as a hexadecimal literals: 0xFF represents 255. A numeric literal is either an integer or a decimal number.1. as already stated. See “Symbol”. To denote a negative number. Decimal literals are a sequence of decimal digits. There are actually two types of supported numeric literals—decimal and hexadecimal. precede a numeric literal with a minus sign (-). A numeric literal is a constant. See SMALLINT andINTEGER for allowed ranges. cannot contain more than 31 digits. or a numeric literal. A decimal literal can be no more than 31 digits long. For example. and Octal Notation” for more information on hexadecimal usage. Hexadecimal literals begin with 0x or 0X characters which are followed by n hexadecimal digits (0 < n <= 29). regardless of the position of the decimal point within the number. a variable data item of INTEGER data type a variable data item of SMALLINT data type a variable data item of DEC data type a variable data item of PIC data type AppBuilder 2. M_APR. it is ambiguous whether the symbol is meant or the rule. You can use symbols to specify “define”. M_JUN. and 12) and the “defines” (M_JAN. 9. 3.85 For a symbol associated with a numeric value. has twelve(12) member symbols with the encoding (1.Symbols in Rules Assume a set MONTHS. see Example .Symbols in Rules.Integer literals An integer numeric literal: 42 A decimal numeric literal: -324. M_FEB. In this case. the rule must have a refers-to relationship with the set that contains the symbol. 7. M_AUG. Symbol You can store character and numeric literals in the repository as symbol entities and group them into sets. To prevent ambiguity the symbol name should be enclosed within parentheses: CASE (symbol IN set) For additional information regarding the use of Symbol in OpenCOBOL. Because you cannot change the value of a symbol in a rule’s code. M_MAY. “encoding”. Symbol Syntax symbol_name IN set_name Usage To use a symbol in a rule. 5. A special case arises when a symbol is used in a CASE statement and the symbol has the same name as a rule. 8. as shown in Figure 3-2.Symbol Examples . M_MAR. Example . 2. see Symbol in OpenCOBOL. M_NOV and M_DEC). 6. M_SEP. 11. M_JUL. a symbol is a constant data item. Using IN Clause If the name of a symbol appears more than once in a rule’s data universe (either in another set or as a field or view name) you must specify the set’s name in an IN clause. and “display”. M_OCT. 3-12 Data Items . 10. 4. Rules normally refer to set symbols by the “define”. not a variable data item. Initialization of a view means recursive initialization of every field of that view. Initialization is performed automatically. and so on: DO FROM M_JAN TO M_DEC INDEX CURRENT_MONTH MAP YEARLY_TOTAL + MONTHLY_TOTALS (CURRENT_MONTH) TO YEARLY_TOTAL ENDDO Initialization The variables in your application are initialized accordingly to their data types in order to prevent them from containing unpredictable values.1.Initialization Figure 3-2 Set MONTHS MONTHS M_JAN (encoding = 1) M_FEB (encoding = 2) M_MAR (encoding = 3) M_DEC (encoding = 12) A rule referring to that set can use the symbol M_JAN exactly as if it were the number 1. When variables are initialized: • The rule and procedure local variables and rule output views are initialized every time a rule is called and before the rule code is executed • The input view of a rule is initialized in the parent rule • Global and all other views are initialized only one time upon application start (main rule start) AppBuilder 2. the symbol M_FEB exactly as if it were the number 2. Different data types are initialized in different ways and variables of different scope are initialized in different moments.1 Rules Language Reference Guide 3-13 . Declaring an Alias DCL Button1 OBJECT ‘Button_1’.00. 1st.00. • DBCS is initialized with ideographic blanks (DBCS spaces) • MIXED is initialized with single-byte spaces • Variables of numeric data types are initialized with zero • Large object data types are initialized with zero length string • Object references are initialized with null reference • DATE variables are initialized with January. In ClassicCOBOL and OpenCOBOL. Object Data Items Default Object Refer to OBJECT and OBJECT POINTER in Java.Object Data Items Initial values for data types include: • BOOLEAN is initialized with FALSE • CHAR is initialized with single-byte spaces • VARCHAR is initialized with zero length string in C and Java. Example . 3-14 Data Items .000 • TIMESTAMP variables are initialized with 0000-00-00-00. 1 AD • TIME variables are initialized with 00.000000 See Java Extensions for additional information related to Initialization and NULL.00.00. Aliases Syntax alias OBJECT ‘system_identifier’ where • alias is any valid Rules Language identifier • system_identifier is the system identifier of an object declared in the panel file Note This method of declaring an alias cannot be used when declaring procedure parameters. Aliases Use a data item of OBJECT data type to assign a name that can be used in Rules Language in place of a system ID to refer to an object. the character portion is initialized to single-byte spaces and the numeric portion is initialized to zeros. or keyword. the original name is no longer available for use. AppBuilder 2. The object must exist in a window used by the rule in which the object is declared. constants. etc. view. only the alias can be used to refer to the object.1. method names. symbol.1 Rules Language Reference Guide 3-15 . therefore. The system ID in the declaration must exactly match the system ID as entered in Window Painter in the property page of a window object..Object Data Items ENDDCL Declaring an alias is useful if: • The system ID is not a valid Rules Language Identifier – a valid Rules ID contains only alphanumeric characters or underscores. to avoid ambiguity errors that may cause failures during prepare. with no empty spaces. The system ID in an alias declaration is a character literal and is. Warning It is strongly advised that you choose a unique name for an alias when using ObjectSpeak names that are the same as keywords. case-sensitive. • The system ID is the same as an existing field. ObjectSpeak object types. set. Once an alias is declared. Object Data Items 3-16 Data Items . then the order of evaluation may lead to different results. symbol.CHAPTER 4 EXPRESSIONS AND CONDITIONS AppBuilder 2. The order of expression and condition evaluation is not guaranteed to be the same as it is written. A view does not qualify as an expression because it does not represent a single value. An expression is any Rules Language construct with a character or numeric value. which you then use to build statements. literal.1. or function that evaluates to a specific value is an expression. Expressions and conditions include: • Character Expressions • Numeric Expressions • DATE/TIME Expressions • Operators • Conditions • Object Method Call • Creating a New Object Instance • ObjectSpeak Expression • ObjectSpeak Conversion Figure 4-1 shows how conditions and expressions can be built from data items. For example: flag = TRUE OR my_date<my_proc(date) In the above example. the second condition (my_date<date) might be evaluated before the first condition (flag = TRUE).1 Rules Language Reference Guide Data items are turned into expressions and conditions. A complex expression is two expressions joined by an operator. AppBuilder 2.1 Rules Language Reference Guide 4-1 . If my_proc changes the value of the flag variable. Any field. This is important because the evaluation of some operands of the expression or condition may lead to unexpected results such as the modification of global variables.1. Character Expressions Figure 4-1 Conditions for Rules Language Statements Expression Syntax Character_expression Numeric_expression Object_expression Character Expressions character_expression ( ++ character_expression ) character_expression character_function procedure_call character_value ObjectSpeak_expression where: ++ character_function procedure_call character_value ObjectSpeak_expression The concatenation of two expressions. See “PERFORM Statement”. See “ObjectSpeak Expression”. See “Character String Functions”. See “Character Value”. 4-2 Expressions and Conditions . The following table shows type and size of concatenation result for different platforms: Table 4-1 Operands CHAR(n) ++ CHAR(m) DBCS(n) ++ DBCS(m) DBCS(n) ++ CHAR(m) DBCS(n) ++ MIXED(m) MIXED(n) ++ MIXED(m) MIXED(n) ++ CHAR(m) Mixed and DBCS Operands Result type and size CHAR(n+m) for all platforms DBCS(n+m) for Java and COBOL MIXED(n+m) in Java. For more information on the concatenation of unsigned integer pictures. MIXED(2*n+m+2) in COBOL MIXED(n+m) in Java MIXED(2*n+m+2) in COBOL MIXED(n+m) for Java and COBOL MIXED(n+m) for Java and COBOL where n and m are length of character value. See “Mathematical Functions”. Numeric Expressions numeric_expression ( operator ) numeric_expression numeric_expression - numeric_expression math_function procedure_call numeric_value ObjectSpeak_expression where: operator math_function procedure_call numeric_value ObjectSpeak_expression See “Operators”. See “PERFORM Statement”.1 Rules Language Reference Guide 4-3 . MIXED and DBCS values can be operands of concatenation in Java.Numeric Expressions ++ (concatenation) This function returns the concatenation of the two input strings. and OpenCOBOL.1. AppBuilder 2. See “Numeric Value”. See “ObjectSpeak Expression”. see the “PIC” description. ClassicCOBOL. in the statement (10 * (5-2)) the inside set of parentheses is first resolved to 3. this is equivalent to 124 DIV 2.B) instead of A MOD . Similarly.47) Because each of those expressions can be plugged back into the expression definition as a subexpression. 12 + 7 is a complex expression which combines them with the addition operator (+) to represent the value 19. left and right parentheses are matched and resolved from the inside out.) When there is more than one set of parentheses in an expression. the following are all expressions: 104366564 + 14223412 PRICE OF ITEM_1 * TAX HOUR OF MILITARY_TIME MOD 12 ROUND(12. Example . 4-4 Expressions and Conditions .3) DIV 2 Note that because of the parentheses. put parentheses around any expression in this format if an operator immediately precedes it: A MOD (. for that order.(HOUR OF MILITARY_TIME MOD 12) TO A To avoid having two operators in a row.389) * 10 + 2 Those expressions can be used to generate even more complex expressions: (104 + 23 .Expressions Both 12 and 7 are numeric literals and hence are expressions.B Parentheses in a complex expression override the normal order of operations. (See “Operators”.Numeric Expressions Using – Expression (unary minus) The unary minus is the shorthand for 0 .expression as in MAP . these are also expressions: 104 + 23 * 3 (104 + 23) * 3 PRICE OF ITEM_1 + PRICE OF ITEM_1 * TAX 60 * (HOUR OF MILITARY_TIME MOD 12) ROUND(5. Similarly. and then the outside set is resolved to 30. DIV. • You cannot use mixed combinations of the DATE and TIME operands. it’s value is used. If one of the operands is DATE (TIME). MOD +. TM TIME. then the other must be either numeric or of the same data type . '%0m/%0d/%0y') TO DT // 05/03/1999 MAP TIME ('1:22:03 PM'. *. '%h:%0m:%0s %x') TO TM // 13:22:03:000 MAP DT + 1 MAP SM + DT TO DT TO DT // 05/04/1999 – next day // 05/05/1999 // 13:22:04:000 – next second // 13:22:05:000 // 05/04/1999 – previous day // 13:22:04:000 – previous second MAP TM + 1000 TO TM MAP I + TM TO TM MAP DT .DATE/TIME Expressions DATE/TIME Expressions You use data items of DATE and TIME data types in numeric expressions with certain limitations: • “-“ (unary minus) is not allowed. **. /. **. ENDDCL MAP 1 TO SM MAP 1000 TO I MAP DATE ('05/03/99'. *. DIV.Using DATE/TIME Expressions DCL DT DATE. Table 4-2 represents valid combinations of operands and the type of result for each combination. Note No arithmetic operations with data items of TIMESTAMP data type are supported.1000 TO TM MAP INT(DT) TO I // 730245 AppBuilder 2. DIV. **. MOD Right operand type DATE (TIME) Numeric Numeric DATE (TIME) DATE (TIME) Result type Numeric DATE (TIME) Numeric DATE (TIME) Numeric Left operand type DATE (TIME) DATE (TIME) DATE (TIME) Numeric Numeric When DATE or TIME is used in arithmetic expression. Use the INT function (page 5-11) to obtain the value of data items of DATE or TIME data type. Example . MOD + -. i.DATE (TIME).1 TO DT MAP TM . SM SMALLINT. Note Precision of the expression with DATE or TIME is calculated with the assumption that the DATE and TIME value has type INTEGER.1. /. -. Table 4-2 Valid Operands Operator +. /. *. I INTEGER.e.1 Rules Language Reference Guide 4-5 . number of days past the date of origin for DATE and the number of milliseconds past midnight for TIME. For instance.Operators MAP DT + DT MAP DT / 2 RETURN TO I // 1460490 (730245 + 730245) TO I // 365122 (730245 / 2) Operators + * / ** DIV MOD +:= -:= The Rules Language supports all basic arithmetic operations.) Generally. That is. You must write and call a user component if you need to perform more complex calculations. the result is calculated before the map operation takes place. the result may also be a SMALLINT data item. MAP SMALLINT_VAR * SMALLINT_VAR TO INTEGER_VAR overflows if the product of the two SMALLINT data items is greater than 32. regardless of the actual type of the target variable. subtraction. and a value of 20. refer to the Developing Applications Guide. For example.767. 2) or larger. 1). This could cause an overflow. the statement MAP 2001 / 100 TO X produces a value of 20 if X is declared as SMALLINT or INTEGER. the precision of an arithmetic operation is controlled by the data item in which the result is stored. a value of 20.0 if X is declared as DEC (3.01 if X is declared as DEC (4. – (Subtraction) The arithmetic operator – subtracts its second expression from its first. The statement MAP 10 + 4 TO X gives X a value of 14. The statement 4-6 Expressions and Conditions . (For more information on user components. + (Addition) The arithmetic operator + adds two expressions together. Caution When you perform an addition. or multiplication operation on two SMALLINT data items. * (Multiplication) The arithmetic operator * multiplies two expressions. 14). The statement MAP 10 / 3 TO X gives X a value of 3.14 ** 2 TO X gives X a value of 9. The statement MAP 3.2 TO X MAP 0.33333333333333.Operators MAP 10 – 4 TO X gives X a value of 6.1 DIV 0.2 TO X MAP 1.1 Rules Language Reference Guide 4-7 . but the result is always an integer.8596.1. DEC (31). Note that the result of the exponentiation operation may be too large to represent in the largest data type.000. The first expression can be any numeric type. ** (Exponentiation) The arithmetic operator ** raises its first expression to the power of its second.2 TO X gives X a value of 55 gives X a value of 5 gives X a value of 0 AppBuilder 2. The statement MAP 10 / 2 TO X gives X a value of 5.11 DIV 0. The statement MAP 10 ** 4 TO X gives X a value of 10. / (Division) The arithmetic operator / divides its first expression by its second. Some other examples of operator DIV are: MAP 11 DIV 0. The statement MAP 11 DIV 2 TO X gives X a value of 5. since 2 fits into 11 five times (with a remainder of 1). The statement MAP 10 * 4 TO X gives X a value of 40. but the second expression must be a SMALLINT or INTEGER on the mainframe and any numeric type on the workstation. DIV (Integer division) The arithmetic operator DIV returns the number of times the second operand can fit into the first. Both operands may be decimal numbers. assuming X was declared as DEC(15. 2 TO X MAP 1. The left operand of this operator must be a numeric variable. If MOD is declared as an INTEGER or SMALLINT. since 2 fits into 11 five times. Because the order of calculation is different on different platforms. the same expression can give different results on different platforms.2 TO X MAP 0. it returns a decimal remainder when the remainder is not a whole number.11 +:= (Increment) The arithmetic operator +:= adds the right operand to the variable which is its left operand. The result is the value of this variable. Use this operator with caution. it will not return a decimal remainder. and the remainder (modulus) is 1. Because the order of calculation is different on different platforms. The right operand must be a numeric data item. The right operand must be a numeric data item. Some other examples of operator MOD are: MAP 11 MOD 0. The result is the value of this variable.1 MOD 0.11 MOD 0. The left operand of this operator must be a numeric variable. The statement MAP 11 MOD 2 TO X gives X a value of 1.1 gives X a value of 0. 4-8 Expressions and Conditions . Use this operator with caution.2 TO X gives X a value of 0 gives X a value of 0. For example: MAP 1 TO I MAP I -:= 1 TO J *>sets I and J to 0<* MAP I -:= 1-1 TO J *> I and J are left unchanged because Decrement operator has the lowest precedence and this statement is equal to MAP I +:= 0 TO J<* The decrement operator modifies its left operand.Operators MOD (Modulus) The arithmetic operator MOD provides the remainder from an integer division operation. the same expression can give different results on different platforms. -:= (Decrement) The arithmetic operator -:= subtracts its right operand from the variable which is its left operand. For example: MAP 1 to I MAP I +:= 1 TO J *> sets I and J to 2<* MAP I +:= 1-1 TO J *> I and J are left unchanged because the Increment operator has the lowest precedence and this statement is equal to MAP I +:= 0 TO J<* The increment operator modifies its left operand. If MOD is declared as a decimal. /.1 Rules Language Reference Guide 4-9 . /. (Unary minus is discussed under “Using – Expression (unary minus)”.1. /. the *. read the following topics: • Comparing Fields with Expression • Comparing Views AppBuilder 2. MOD. MOD. ** *. -:= lowest Arithmetic operator precedence Precedence highest Conditions A condition is an expression that evaluates to either true or false. Table 4-3 summarizes the order of precedence of the arithmetic operators.Conditions Operator Precedence As in most programming languages. and DIV.) Table 4-3 Operator unary minus. DIV +. All the arithmetic operators take precedence over the relational and Boolean operators. You can use parentheses in the expression syntax to override the order of operations. unary minus and the exponential operator take precedence over *. and DIV operators take precedence over the + and operators. MOD. Also. +:=. A condition can be one of two types: • Relational Condition (with relational ISCLEAR Operator or INSET Operator) • Boolean Condition For additional details. Conditions Condition Syntax expression = <> < <= > >= INSET ( condition ) condition AND OR NOT ISCLEAR view_name field_name expression set_name condition where expression is explained in Expression Syntax. Boolean. Object. you can compare any objects for equality or inequality. View Numeric. except for ISCLEAR Operator or INSET Operator. the condition’s truth or falsity depends on the value of the data item. Date and Time. View Set Any Variable or View Relational Operator = <> < <= > >= INSET ISCLEAR Note In C mode. View Numeric. you cannot compare for equality or inequality aliases and variables of type OBJECT ARRAY. Large Object. the comparisons. Character. Character. View Numeric. Character. Large Object. Table 4-4 Relational Operators Comparison Is equal to Is not equal to Is less than Is less than or equal to Is greater than Is greater than or equal to Is included in the set Is operand value equal to its initial value Applicable to Data Types Numeric. Character. View Numeric. In Java mode. It consists of an expression followed by a relational operator followed by another expression. Relational Condition A relational condition compares one expression to another. Large Object. The two expressions must resolve to compatible values. Date and Time. Date and Time. Character. 4-10 Expressions and Conditions . Large Object. Date and Time. Character. Date and Time. View Numeric. and the data type variables that each applies to. Large Object. Object. Boolean. If either expression is a variable data item. Table 4-4 lists the relational operators. Large Object. Date and Time. MAR. FEB.ELSE. 3. it just sets the rule’s return code to UPDATE. Table 4-5 Allowed left operand types for INSET operator with characters sets Set Type CHAR Left Operand CHAR MIXED DBCS x x Conversion function MIXED X X X DBCS Conversion function X X AppBuilder 2. because the set MONTHS does contain a value entity whose value property is 3: the value with the symbol MAR. Assume there is a set MONTHS in a rule’s data universe that contains the symbols JAN. If set type is MIXED then the left operand can be either MIXED.. 12. The data type of the expression must be compatible with that of the value entity.Conditions A relational condition can be the argument to a flow-of-control statement to allow it to choose among different actions depending on the condition’s veracity. because there is no such member value in MONTHS. If it is not true.. These Left operand types are summarized in Table 4-5. CHAR. the name of a set must follow an INSET operator.1. In the code sample below. In that rule’s code. because the MONTHS set is numeric and the literal data item DECEMBER is character. The condition 26 INSET MONTHS is false. The condition 'DECEMBER' INSET MONTHS is illegal. If it is.ENDIF statement checks whether the condition RETURN_CODE OF UPDATE_CUSTOMER_ DETAIL_O = 'FAILURE' is true.Sample Relational Condition Code MAP CUSTOMER_DETAIL TO UPDATE_CUSTOMER_DETAIL_I USE RULE UPDATE_CUSTOMER_DETAIL IF RET_CODE OF UPDATE_CUSTOMER_DETAIL_O = 'FAILURE' MAP 'CUSTOMER_DETAIL_FILE_MESSAGES' TO MESSAGE_SET_NAME OF SET_WINDOW_MESSAGE_I MAP UPDATE_FAILED IN CUSTOMER_DETAIL_FILE_MESSAGES TO TEXT_CODE OF SET_WINDOW_MESSAGE_I MAP 'CUSTOMER_DETAIL' TO WINDOW_LONG_NAME OF SET_WINDOW_MESSAGE_I USE COMPONENT SET_WINDOW_MESSAGE ELSE MAP 'UPDATE' TO RET_CODE OF DISPLAY_CUSTOMER_DETAIL_O ENDIF INSET Operator Unlike other relational operators. A condition with an INSET clause is true if the expression on the left evaluates to a value that is equal to a value entity related to the set on the right. the IF.1 Rules Language Reference Guide 4-11 .…. DEC. or DBCS. In all other cases. APR. the explicit conversion function is required... then the left operand can be either DBCS or MIXED. 4…. the condition 3 INSET MONTHS is true. either both numeric or both character. Example . 2. If the set type is CHAR then the left operand can be either MIXED or CHAR. it displays an error message window. If the set type is DBCS. representing the values 1. Comparison of views has undefined consequences and changes in code generation may result in changes in behavior. MIXED variables are considered clear if they contains blanks only. such as: NOT (A = B) AND (C INSET D OR E = F) ISCLEAR Operator The ISCLEAR condition tests TRUE if the variables (or all fields of a view) are set to their initial value and returns FALSE if a variable (or at least one field in a view) differs from it's initial value. it will return TRUE if this reference actually refers to nothing (it contains a null value and FALSE otherwise).. This is not recommended. Example . If you wish to test a variable of any object type in Java and any except OBJECT ARRAY and aliases in C mode (“Object Data Types”) for null. “Data Items” for more information. a condition can be built up like an expression: IF (A > B AND NOT (C <= D OR E = F)) OR G INSET SET_H. Order of Operations with INSET The condition NOT A = B AND C INSET D OR E = F is equivalent to ((NOT (A = B)) AND (C INSET D)) OR (E = F) You can change this order using parentheses to something else.Conditions Boolean Condition with INSET Since the subconditions can also be Boolean. by using the CLEAR statement or by moving a zero to a numeric field).. Note Before the ISCLEAR was supported. See the Initialization topic in Chapter 3. 4-12 Expressions and Conditions . A field is considered to be set to its initialized value if it has never been modified by a user or if it has been reset programmatically: for example. use ISCLEAR instead of ISNULL. doesn't matter double-byte or singlebyte ones. view comparison was sometimes used to check if a view was modified. Use ISCLEAR instead.Using ISCLEAR IF ISCLEAR(VIEW1) USE RULE RULE1 ENDIF Order of Operations with ISCLEAR The condition NOT ISCLEAR C AND C INSET D OR E=F is equivalent to ((NOT (ISCLEAR C)AND(C INSET D))OR(E=F) You can change this order by changing position of the parentheses. according to the rules of Boolean algebra: • condition AND condition is true only if both conditions are true • condition OR condition is true only if one or both conditions are true • NOT condition is true only if the condition is false The result of relational and Boolean conditions has a BOOLEAN type (See “BOOLEAN Data Type”). In the case of variables holding the result of a comparison. These topics describe the various methods of comparison and their restrictions: • Comparing Character Values • Identifying Illegal Comparisons • Order of Operations • Comparing Views for C • Comparing Views for Java • Comparing Views for ClassicCOBOL and OpenCOBOL AppBuilder 2. if the values change later. Variables of a Large Object data type (IMAGE or TEXT) can be compared with each other and with character data items (CHAR or VARCHAR) in any combination. This is useful if you want to use the same condition several times. or • The Boolean operator NOT followed by a condition. using a variable holding the result of a comparison is not the same as the comparison function itself. The conditions in a Boolean condition can be either relational or Boolean. See PIC for more information. This allows the use of conditions in statements not limited to condition statements. For example. IsSameCustomer is not updated. Comparing Fields with Expression A PIC field can be compared to either a numeric or a character expression. you can store the results of a comparison for later use with the statement: MAP CUSTOMER_NAME OF UPDATE_DETAILS_WND_IO = CUSTOMER_NAME OF CURRENT_CUSTOMER_V TO IsSameCustomer and use the variable IsSameCustomer (of type BOOLEAN) later. the result is not updated. The true or false value of a Boolean condition is determined by the values of its two conditions.1. in the case above. the variables are compared only once.1 Rules Language Reference Guide 4-13 .Conditions Boolean Condition A Boolean condition is either: • Two conditions joined by the Boolean operators AND or OR. However. For example. is an error because it compares two literals. DBCS (double-byte character set) strings are compared according to system locale settings. “abc” is less than “ABC” on the host. ClassicCOBOL and OpenCOBOL. either ASCII (on the workstation in C mode). the character order for DBCS string on the PC may differ from the character order of the same string in Unicode. so IF MARY IN NAMESET = 4… is legal. DBCS values are padded with double-byte spaces. if A = 'Hello' and B = 'Hello ' and C = 'Hello '. Blanks at the end of a string are ignored when comparing that string for equality to another character expression. using the collating sequence of the hardware execution platform. In Java. you can also compare DBCS and CHAR with MIXED values. CHAR values are padded with singlebyte spaces. CHAR and DBCS values can also be compared. both in C and Java mode. For instance. For MIXED values. However. Since 7-bit ASCII is included into Unicode (which is used in Java). (DBCS and CHAR values are implicitly converted to MIXED using the corresponding conversion function. because the numeric values of ASCII and EBCDIC alphabetic characters differ. the shorter string is padded with spaces (double-byte or single-byte) to the length of longer string.<= or >=.>.Conditions Comparing Character Values You can compare character values using all the relational operators except ISCLEAR and INSET. DBCS symbol in one code page might have different code in another. while conforming to the syntactic definition of a condition. you can assume that collation of all strings containing only 7-bit ASCII symbols remains the same. then the following conditions are all true: A = B B = C C = A When comparing strings using relational operators <. DBCS is translated to Unicode by the Java compiler. but Unicode supports virtually all code pages. For example.<= or >=. thus.>.) The comparison is performed character to character not byte to byte. When a single-byte character is compared to a double-byte character. the double-byte character is considered greater than the single-byte character. Identifying Illegal Comparisons • A condition (even if it evaluates to true or false) is illegal if it compares two literals. blanks at the end of each string are removed and the smaller item is padded with spaces corresponding to type of character in that position in the longer string. but greater than “ABC” on the workstation. A condition that compares only a literal to a set symbol is permitted. 3 < 29. Thus. or if it cannot be true due to the data types of its expressions. In Java. Any such comparison is a straight binary comparison. Consider these differences when preparing and using your application in Java mode. if MIXED or DBCS literals are compared to a literal of any other legal data type using <. Unicode (in Java mode) or EBCDIC (on the host). this is considered a legal comparison and is performed at runtime (while a 4-14 Expressions and Conditions . Order of Operations The order of operations for the relational and Boolean operators. This is done because of possible differences between compile-time and run-time codepages.Conditions comparison of two CHAR literals is performed at compile time). then the condition SALARY > 1. Similarly. =. Consequently. >. <=.1.000 would be illegal. All the arithmetic operators take precedence over the relational and Boolean operators. <=. in decreasing precedence. You cannot compare wildcards or ranges. Table 4-6 Operator INSET. • You cannot compare a PIC field formatted without a negative sign to an expression whose value is negative. is shown in Table 4-6. For example. <. if TOTAL were a PIC field without a sign.767 or less than -32.1 Rules Language Reference Guide 4-15 . In particular. it generally is not recommended that you use view comparisons.000. parentheses override the usual order of operations. • You cannot compare a SMALLINT field to an expression with a value greater than 32. because it would necessarily be false. then the expression X = “JULY” would be invalid. For additional information see the following: • Comparing Views for C • Comparing Views for Java • Comparing Views for ClassicCOBOL and OpenCOBOL AppBuilder 2. For example. If SALARY were a field of data type SMALLINT. you cannot compare a field of data type INTEGER to an expression whose value is not within the limits for values storable in INTEGER fields. >= NOT AND OR lowest Relational and Boolean Operator Precedence Precedence highest Comparing Views You can compare views using standard relational operators (<. ISCLEAR =. you could not use the condition P < 0. >. and because the future implementation of view comparison is subject to change. because SALARY could not contain a value enabling the condition to be true. if MONTH were CHAR (3). >=.767. <>. • You cannot compare a character constant to a character field that it doesn’t fit into. and <>). do not use view comparison to check if a view has been modified. instead use the ISCLEAR function (see ISCLEAR Operator). As with expressions. and properties. New Object Syntax NEW ‘ class_identifier ‘ parameters_list class_name where: parameters_list is the list of object constructor parameters included in round brackets.Object Method Call Object Method Call OBJECT_data_item . parentheses may be omitted. if constructor has no parameters then empty brackets must be omitted. see Creating a New Object Instance for Java. method_name actual_parameters_list where: actual_parameters_list is a list of actual parameters delimited with commas and enclosed in parentheses. If a method does not have parameters then empty parentheses (()) can be written. If the list is empty. For more information see: • Object Method Call in C • Object Method Call in Java Creating a New Object Instance This clause is used in Java application development to create new instances of objects. ObjectSpeak Expression ObjectSpeak is an extension to Rules Language that allows you to: • Invoke methods of objects supplied with the AppBuilder product Note For a list of available objects. refer to the ObjectSpeak Reference Guide. methods. 4-16 Expressions and Conditions . For an example. method2(parm). a property that is returned by a method of the control or a property of a property of the control are nested.TextXPos MAP myAnimatedButton. You can use such an expression in any statement in which an ordinary expression can be used. property_name method_name . followed by a period.Handle In this example. The simplest expression is the name of an object.ObjectSpeak Expression ObjectSpeak Expression Syntax object_name .” For example: myGauge.method1(parm. For example: MAP 12 TO myAnimatedButton. suppose there is a property named “Text” that is nested in this way (where method2 returns an object of type BitMapButton): Object_name. simply use a period to separate each “nesting level. When a property is nested.1 Rules Language Reference Guide 4-17 .Speed TO saveSpeed Nested Properties Sometimes a property of a control is “buried” inside the control. followed by the name of the property.Text See “Expression Syntax”. you can use an object (see “Object Data Types”) to abbreviate the property reference.parm).1.Text If you declare an object as follows (where theBitMapButton is an arbitrary name): DCL theBitMapButton OBJECT TYPE BitMapButton of GUI_KERNEL ENDDCL then you can abbreviate references to the “Text” property. the nesting can go to any level. When a property is deeply nested inside a control. ( expression ) where: expression and object_name can be: • The system identifier (ID) of the object • The alias of the object (see “Object Data Items”) • An object (see “Object Data Types”) • An array (see “Array Object”) Referencing Properties You can use ObjectSpeak expressions to reference an object’s properties. In theory. Handle is a property of the Picture property of the Gauge control named “myGauge”. AppBuilder 2. For example. as follows: theBitMapButton. For example.Picture. the method invocation can be a constituent of an expression. ObjectSpeak Conversion This is the conversion performed between Java standard data types and Rules types when passing parameters to and accepting return values from Java methods. see: • “Numeric Type” • “String Type” • “OBJECT Type” • “Boolean Type” • “Date and Time Type” 4-18 Expressions and Conditions . see “ObjectSpeak Statement”. Note Refer to the ObjectSpeak Reference Guide for more information about ObjectSpeak. For information on invoking a method. For information on specific types.ObjectSpeak Conversion Methods Because methods can return a value. 1. and returns a value based on the action. Functions include: • Numeric Conversion Functions • Mathematical Functions • Date and Time Functions • Character String Functions • Double-Byte Character Set Functions • Dynamically-Set View Functions • Error-Handling Functions • Support Functions • Java Extensions Function Syntax numeric_conversion_function mathematical_function date_and_time_function character_function error_handling_function support function AppBuilder 2. performs an action on them. a space is optional between a function’s name and any parentheses that enclose its arguments.1.1 Rules Language Reference Guide A function accepts one or more arguments.CHAPTER 5 FUNCTIONS AppBuilder 2.1 Rules Language Reference Guide 5-1 . See “Target Language Support Tables” and “Release Specific Considerations” for a summary of platform and release support. A function is considered an expression because it evaluates to a single value. For all functions. and a second expression of -2 refers to the hundreds column to the left of the decimal point. The result of the DECIMAL function must fit into the DEC Rules data type. assuming it is declared as DEC(10. a second expression of 2 refers to the hundredths place. When using CEIL. for example <* Mathematical Functions The mathematical functions allow you to mathematically modify an expression.34") TO DECIMAL_FIELD *> DECIMAL_FIELD will be set to 12. For the INT function. the first expression is the value to be modified. For instance. ROUND and TRUNC only return a value calculated based on the arguments. format string Examples MAP INT("1234") TO INTEGER_FIELD *> INTEGER_FIELD will be set to 1234 <* MAP DECIMAL("12. Numeric Conversion Syntax INT DECIMAL ( character data item ) . otherwise the result is unpredictable. For restrictions. the modulo of the result of conversion must be an integer not exceeding 231–1. ROUND and TRUNC. zero referring to the digit to the immediate left of the decimal point. CEIL. the DECIMAL function returns DEC of appropriate length and scale. Mathematical Function Syntax 5-2 Functions .Numeric Conversion Functions Numeric Conversion Functions The numeric conversion functions INT and DECIMAL convert character strings to numeric (integer or decimal) values. INCR and DECR modify their arguments. An omitted second expression is the equivalent of 0. but the other mathematical functions do not. 4). and a negative value referring to digits further to the left of the decimal point.. The second expression specifies the significant number of digits to which the function applies—a positive value referring to digits to the right of the decimal point. The INT function returns INTEGER. FLOOR.34. The difference between the INT function and the DECIMAL function is the return type. and applies the function to the nearest integer value. FLOOR. The data type of the returned value for any of these functions is DEC. see Release Specific Considerations. 5678) (-1234.1. -1) TO TO TO TO TO TO TO TO X X X X X X X X *> *> *> *> *> *> *> *> sets sets sets sets sets sets sets sets X X X X X X X X to to to to to to to to 1234.5678.5678. The ROUND function observes the usual rounding conventions (0–4 for rounding down. FLOOR Examples MAP MAP MAP MAP MAP MAP MAP MAP ROUND This function returns the number closest to the first expression to the significant number of digits indicated by the second expression. 1) (-1234.56 1234. 5–9 for rounding up).5678. CEIL Examples MAP MAP MAP MAP MAP MAP MAP MAP FLOOR This function returns the next number less than the first expression to the significant number of digits indicated by the second expression. numeric_expression ) ( variable_data_item ) . returns the next number greater than the first expression to the significant number of digits indicated by the second expression. 1) (1234. where numeric_expression variable_data_item CEIL The CEIL function.5678.6 -1235 -1240 <* <* <* <* <* <* <* <* CEIL CEIL CEIL CEIL CEIL CEIL CEIL CEIL (1234. a variable data item of any numeric type AppBuilder 2.5678) (1234. 2) (1234.5678.5678. -1) (1234.5 1234 1230 1200 -1234.5678) (1234.Mathematical Functions CEIL FLOOR ROUND TRUNC INCR DECR ( numeric_expression .5678.5678. 1) (-1234.5 -1234 -1230 <* <* <* <* <* <* <* <* See “Numeric Expressions”. FLOOR FLOOR FLOOR FLOOR FLOOR FLOOR FLOOR FLOOR (1234.6 1235 1240 1300 -1234.5678.5678. The second expression must always be greater than or equal to -10 or less than or equal to 10 (-10 ≤x ≤10).5678) (-1234. -2) (-1234. It sets any rounded digits to zero. 2) (1234. -1) (1234.5678.1 Rules Language Reference Guide 5-3 .5678. -1) TO TO TO TO TO TO TO TO X X X X X X X X *> *> *> *> *> *> *> *> sets sets sets sets sets sets sets sets X X X X X X X X to to to to to to to to 1234. 1) (1234. which is short for ceiling. -2) (-1234.57 1234. 5678) TO X (1234.5678.56 1234.5678. returns a number that is the first expression with any digits to the right of the indicated significant digit set to zero.6 -1235 -1230 <* <* <* <* <* <* <* <* 5-4 Functions .6 1235 1230 1200 -1234.5678) TO X (-1234.5678. This function can be used in an expression and as a statement.57 1234. 2) TO X (1234. the same expression can give different results on different platforms.5678. -1) TO X (1234. 1) TO X (1234.5678.5678.5 1234 1230 1200 -1234. J is left unchanged<* INCR(I. 2) TO X (1234. J is left unchanged<* MAP 1 TO I. -1) TO X *> *> *> *> *> *> *> *> sets sets sets sets sets sets sets sets X X X X X X X X to to to to to to to to 1234.2) TO J *>sets I and J to 4<* INCR(I.5678.first parameter must be a variable<* MAP 1 TO I MAP INCR(I) TO J *>sets I and J to 2<* MAP INCR(I.J+1) *>sets I to 13. 1) TO X (1234. -1) TO X *> *> *> *> *> *> *> *> sets sets sets sets sets sets sets sets X X X X X X X X to to to to to to to to 1234. Use this function in expressions with caution. 1) TO X (-1234. adds its second parameter to its first parameter and returns this modified first parameter. which is short for truncate. -2) TO X (-1234. -1) TO X (1234. which is short for increment. INCR adds 1 to the first parameter and returns the modified first parameter. TRUNC Examples MAP MAP MAP MAP MAP MAP MAP MAP INCR The INCR function. It removes a specified number of digits from the first expression.5 -1234 -1230 <* <* <* <* <* <* <* <* ROUND ROUND ROUND ROUND ROUND ROUND ROUND ROUND (1234.5678.5678. If the second parameter is omitted.first parameter must be a variable<* MAP INCR(I+1) TO I*>Wrong .J MAP J+INCR(I) TO J *<sets I to 2 and J to 3<* TRUNC TRUNC TRUNC TRUNC TRUNC TRUNC TRUNC TRUNC (1234.5678.5678.5678. INCR Examples MAP INCR(1)+1 TO I*>Wrong .J) *>sets I to 8. 1) TO X (-1234.5678) TO X (-1234. Because the INCR function modifies its left operand and the order of calculation is different on different platforms.5678) TO X (1234. -2) TO X (-1234.Mathematical Functions ROUND Examples MAP MAP MAP MAP MAP MAP MAP MAP TRUNC The TRUNC function. you can run any rules that call for a date. DECR subtracts 1 from the first parameter and returns the modified first parameter.J) *>sets I to 0. and the data type of the returned field are listed below.2) TO J *>sets I and J to 10<* DECR(I.J+1) *>sets I to -11.1. Alternatively. J is left unchanged<* MAP 1 TO I.Date and Time Functions DECR The DECR function.first parameter must be a variable<* MAP 13 TO I MAP DECR(I) TO J *>sets I and J to 12<* MAP DECR(I.J MAP J+DECR(I) TO J *<sets I to 0 and J to 1<* Date and Time Functions Use a date and time function to obtain the current date and time. which is short for decrement. time. DECR Examples MAP DECR(1)+1 TO I*>Wrong . the same expression can give different results on different platforms. The system date. subtracts its second parameter from its first parameter and returns this modified first parameter. If the second parameter is omitted. and timestamp are unique to each workstation. The date and time functions. time. AppBuilder 2. the data type of the source field. to format your data. Because the DECR function modifies its left operand and the order of calculation is different on different platforms. J is left unchanged<* DECR(I. or to convert a field from a date and time data type to another data type.1 Rules Language Reference Guide 5-5 .first parameter must be a variable<* MAP DECR(I+1) TO I*>Wrong . This function can be used in an expression and as a statement. or timestamp on the host. Use this function in expressions with caution. You (or your system administrator) must synchronize your workstations if you want the values to be consistent. time_field . See “Date and Time Data Types”. format_string timestamp_field integer_field TIMESTAMP ( date_field . See “Format String”. fraction ) FRACTION CHAR ( timestamp_field ) ( date_field time_field ) . 5-6 Functions . See “Numeric Data Types”. See “Date and Time Data Types”. format_string time_field date_field INT ( ) NEW_TO_OLD_DATE NEW_TO_OLD_TIME OLD_TO_NEW_DATE OLD_TO_NEW_TIME ( date_field ) ( time_field ) ( integer_field ) where: character_expression date_field time_field integer_field format_string timestamp_field See “Character Expressions”.Date and Time Functions Date and Time Function Syntax DAY MONTH YEAR DAY_OF_YEAR DAY_OF_WEEK SECONDS MILSECS MINUTES HOURS SECONDS_OF_DAY MINUTES_OF_DAY DATE TIME ( date_field ) ( time_field ) ( character_expression ) . See “Date and Time Data Types”. DAY_OF_YEAR The DAY_OF_YEAR function determines the date that the value in the specified date field represents and returns the Julian day of the year for that date in a SMALLINT field.1 Rules Language Reference Guide 5-7 .Date and Time Functions See these related topics for detailed information: • Date and Time Function Definitions • Format String • Common Separators • Date Format String • Time Format String • Input String Restrictions • Sample Date and Time Functions Date and Time Function Definitions DAY The DAY function determines the date that the value in the specified date field represents and returns the day of the month for that date in a SMALLINT field. YEAR The YEAR function determines the date that the value in the specified date field represents and returns the year for that date in a SMALLINT field. MILSECS The MILSEC function determines the time that the value in the specified time field represents and returns the number of milliseconds past the second for that time in a SMALLINT field. SECONDS The SECONDS function determines the time that the value in the specified time field represents and returns the number of seconds past the minute for that time in a SMALLINT field. AppBuilder 2. DAY_OF_WEEK The DAY_OF_WEEK function determines the date that the value in the specified date field represents and returns the day of the week for that date in a SMALLINT field. MONTH The MONTH function determines the date that the value in the specified date field represents and returns the month of the year for that date in a SMALLINT field.1. Without an argument. and returns the value in a TIMESTAMP field. 5-8 Functions . With a value in a TIMESTAMP field as an argument. HOURS The HOURS function determines the time that the value in the specified time field represents and returns the number of hours since midnight for that time in an SMALLINT field. date. and fraction. time. this function returns the number of picoseconds. it concatenates the three fields. On workstations. See the following for details: • “Date and Time Functions in C” • “Date and Time Functions in Java” • “Date and Time Functions in OpenCOBOL” TIMESTAMP You can use this function with or without arguments. Without arguments. If you omit the format string. the default format string will be provided. See Release Specific Considerations. SECONDS_OF_DAY The SECOND_OF_DAY function determines the time that the value in the specified time field represents and returns the number of seconds since midnight for that time in an INTEGER field. it determines the value the date portion of that field represents and returns that date in a DATE field and the time portion of that field represents and returns that time in a TIME field. With arguments. DATE and TIME You can use these functions with or without an argument. DATE and TIME with DBCS and MIXED argument is available in Java and COBOL modes for DBCS enabled releases. it returns a timestamp created from the current date and time in a TIMESTAMP field. On the host. FRACTION The FRACTION function determines the timestamp represented by the value in the specified timestamp field and returns the number of picoseconds for that timestamp in an INTEGER field. these functions convert the character value to a date in a DATE field or a character value to a time in a TIME field. With a character value as an argument. See “Format String” for tokens to use in a format string. this function always returns 0 because it is not feasible to obtain a unit of time smaller than a millisecond.Date and Time Functions MINUTES The MINUTES function determines the time that the value in the specified time field represents and returns the number of minutes past the hour for that time in an SMALLINT field. MINUTES_OF_DAY The MINUTES_OF_DAY function determines the time that the value in the specified time field represents and returns the number of minutes since midnight for that time in an SMALLINT field. DATE returns the current system date in a DATE field and TIME returns the current system time in a TIME field. It interprets the character value according to a format string. 1 Rules Language Reference Guide 5-9 . The Julian day of the year for that date in a SMALLINT field. OLD_TO_NEW_DATE The OLD_TO_NEW_DATE function converts the value in the specified integer field to a value in a DATE field.. Returns. The month of the year for that date in a SMALLINT field. See Format String for tokens to use in a format string. The number of seconds past the minute for that time in a SMALLINT field. The date that the value in the specified date field represents. The number of milliseconds past the second for that time in a SMALLINT field. The date that the value in the specified date field represents. It formats the character value according to the system default unless you provide a format string. The date that he value in the specified date field represents. The date that the value in the specified date field represents. OLD_TO_NEW_TIME The OLD_TO_NEW_TIME function converts the value in the specified integer field to a value in a TIME field. NEW_TO_OLD_TIME The NEW_TO_OLD_TIME function converts the time in the specified time field to a value in an INTEGER field. NEW_TO_OLD_DATE The NEW_TO_OLD_DATE function converts the date in the specified date field to a value in an INTEGER field.. The year for that date in a SMALLINT or INTEGER field. If the DATE/TIME value is invalid. The time that the value in the specified time field represents. Table 5-1 Date and Time Functions Determines. See “Date and Time Functions in OpenCOBOL” for exception. -1 is returned.. The day of the month for that date in a SMALLINT field. The date that the value in the specified date field represents.1. The day of the week for that date in a SMALLINT field.Date and Time Functions See “FRACTION in OpenCOBOL” for more information. CHAR This function converts a value in a DATE or TIME field to a value in a CHAR field. INT The INT function converts the time or date in the specified time or date field to a value in an INTEGER field. Function Name DAY MONTH YEAR DAY_OF_YEAR DAY_OF_WEEK SECONDS MILSECS AppBuilder 2. The date that the time in the specified date field represents.. The time the value in the specified time field represents. The time the value in the specified time field represents.. Format string is specified by the DEFAULT_DATE_FORMAT setting of [NC] section of appbuilder. ClassicCOBOL. The time the value in the specified time field represents Without an argument With a value in a TIMESTAMP field as an argument. The time that the value in the specified time field represents. the default system value (Java regional setting) will be used. The number of seconds since midnight for that time in an INTEGER field.Date and Time Functions Table 5-1 Date and Time Functions (Continued) Determines. See “Format String” for tokens to use in a format string. it determines the value that the date portion of that field represents. If the appbuilder. DATE You can use this function with or without an argument. With a character value as an argument. If the HPS. It interprets the character value according to a format string. 2. The number of minutes since midnight for that time in a SMALLINT field. If you omit the format string.INI setting is not specified. the ISO format is used: "%Y-%0m-%0d" For Java mode: 1. The number of minutes past the hour for that time in a SMALLINT field.INI or on the mainframe in the CODEGEN ini of CGTABLES. The number of hours since midnight for that time in a SMALLINT field.. Format string specified by the DFLTDTFMT setting of the [CodeGenParameters] section of HPS. 5-10 Functions .. Function Name MINUTES HOURS SECONDS_OF_DAY MINUTES_OF_DAY The date in a DATE field.. the following default format strings will be provided: For C. The current system date in a DATE field. 2.ini setting is not specified. this function converts the character value to a date in a DATE field. and OpenCOBOL modes: 1. Returns.ini. the following default format string will be provided: For C. it concatenates the three fields. Converts the date in the specified date field to a value in an INTEGER field. this function always returns 0 because it is not feasible to obtain a unit of time smaller than a millisecond. CHAR INT NEW_TO_OLD_DATE NEW_TO_OLD_TIME AppBuilder 2.INI setting is not specified. See “Format String” for tokens to use in a format string.ini. On the host.Date and Time Functions Table 5-1 Date and Time Functions (Continued) Determines.1 Rules Language Reference Guide 5-11 .... The current system time in a TIME field. The number of picoseconds for that timestamp in an INTEGER field. this function returns the number of picoseconds. Returns. the default system value (Java regional setting) will be used. It formats the character value according to the system default unless you provide a format string. It interprets the character value according to a format string. FRACTION Converts a value in a DATE or TIME field to a value in a CHAR field. it determines the value the time portion of that field represents.ini setting is not specified. and OpenCOBOL modes: Format string specified by DFLTTMFMT setting of [CodeGenParameters] section of HPS.1. Without arguments A timestamp created from the current date and time in a TIMESTAMP field. With arguments. this function converts the character value to a time in a TIME field. Converts the time in the specified time field to a value in an INTEGER field. The timestamp represented by the value in the specified timestamp field.INI or on the mainframe in the CODEGEN ini of CGTABLES.%0s" For Java mode: Format string is specified by DEFAULT_TIME_FORMAT setting of [NC] section of appbuilder.%0m. The returned value is formatted as specified in the “Data Types” data types. TIMESTAMP You can use this function with or without arguments. If the HPS. The value in a TIMESTAMP field. On workstations. Converts the time or date in the specified time or date field to a value in an INTEGER field. TIME You can use this function with or without an argument. ClassicCOBOL.. If you omit the format string. If the appbuilder. the ISO format is used: "%0t. Function Name The time in a TIME field. See Format String for tokens to use in a format string. With a character value as an argument. Without an argument With a value in a TIMESTAMP field as an argument. If this key is set to “2000”. for instance. use a format string to tell the system how to interpret a character value when converting it to a value in a date or time field. For a CHAR function. all date and time functions assume twenty-first (21st) century when dealing with twodigit years (that is. If you do not provide a format string. The AM/PM flag can be specified in the following forms: 5-12 Functions . • A format string is case-sensitive. DATE (‘m%f%y’)—the rule prepares successfully. by default. This is because the format string ‘m%f%y’ is a valid literal string. Format String For a DATE or TIME function. Provide one token for each element of the date or time. For a date value. The following limitations also apply to these functions: • The returned value depends on the current NLS settings. The separators are common to DATE and TIME fields.. all two-digit years are preceded by 19). This means that a format string is not validated during preparation and a statement with an incorrect format string prepares successfully. Converts the value in the specified integer field to a value in a DATE field. • A format string is not interpreted until runtime.. Converts the value in the specified integer field to a value in a TIME field. Returns. that argument is considered to be the input string. Therefore. Table 5-3 and Table 5-4 list the tokens you can place into a format string. A format string consists of a series of tokens enclosed in single quotes. %t or %H. if an incorrect template is specified as the only argument—for example.INI [AE run-time] section DEFAULT_CENTURY key. Separate the tokens with the same separators used in the provided value. the template provided in the language configuration file is used (See “Date and Time Data Types” for more information. one for month.. • If only one argument is specified. You can provide these tokens either as a literal or in a character variable. not the format string. any value stored in a date or time field may be ambiguous.. You may control this behavior by setting the HPS. If you do not use a separator. all two-digit years are preceded by 20). but the other tokens are not. a numeric function returns a value of -1 and a character function returns the null string. provide one token for day.) • The %x time token is ignored with either %0t. the default system format as set during installation is used. If you do not provide a format string. • If a function cannot convert an input string. Function Name OLD_TO_NEW_DATE OLD_TO_NEW_TIME Note All the date and time functions that deal with years assume by default a twentieth (20th) century when they encounter two-digit years in their parameter (so. use a format string to format a value in a date or time field when converting it to a character field.Date and Time Functions Table 5-1 Date and Time Functions (Continued) Determines. See “Date and Time Data Types” for the default format. and one for year. 12). A./P.%c%0y’) returns -1 because 1998 is considered century and %c accepts an unlimited number of digits. and day in the DATE function and one token must be specified for hours and minutes in the TIME function. %f for TIME function. TIME (‘125’. For example: Procedure TIME (‘1 25’. %y. • TIME (":25". %j for DATE function or %h. Any symbol can be used as a delimiter. %m. %d.M..M. Common Separators Use the separators in Table 5-2 for both date and time values. ‘%m/%Y’) is invalid because the value for the day is missing. ‘%h%m’) is ambiguous and can be interpreted as 12:05 or 1:25 because the tokens are defined as • %h = Hour. it can be either 1 or 23 • The AM/PM flag can be specified in the TIME function in the form: AM/PM. the result is the first year of that century. • DATE (‘12/1998’.M.01. -1 is returned as a result. Otherwise.59) Note This restriction currently applies only to DATE and TIME functions.M.. • DATE (‘12/23/01/1998’.1998’.1 Rules Language Reference Guide 5-13 . it is not enforced for the CHAR function. • TIME (‘:25’. • One token must be specified for year. month. %c. ‘%d. This occurs because these tokens accept an unlimited number of digits./P. • -1 is returned as a result where a format string contains two tokens in sequence that are not delimited by a separator and first of the tokens is %m. %t.12) • %m = Minute. • If more than one token of the same type is specified (%y and %Y or %D and %d) in the DATE or TIME functions.1. AppBuilder 2. See also Date and Time Functions in OpenCOBOL. A M/P M.Date and Time Functions AM/PM. then an error with the result of -1 is returned.. ‘%m/%d/%0d/%Y’) is invalid because the value of the day token is ambiguous.%m. %s. ‘:%m’) is invalid because the value for the hour is missing. ‘%h %m’) returns 1:25 DATE (‘12. numeric (0. Note If the century token is specified and the year token is not. A M/P M. numeric (0. so there is no value for the year. A. '%h:%m') is invalid because %h means there should be at least one digit in the hour value (0. with the first two digits implied to be 19a Year. Julian. with leading zero (01…12) Hour. word (Sunday…Saturday) Example 2 02 February 28 28 28th 59 (Feb. numeric. numeric. numeric. word (one. 28) 59 (Feb. with leading zero (00…23) Hour.twelve) Example 2 02 14 14 Eleven 5-14 Functions . . numeric. numeric (0…23) Hour. word (January…December) Day. last 2 digits (00…99). numeric (1…31) Day. Format String Separators Date Format String Use the tokens in Table 5-3 when formatting a DATE value. Julian (1…366) Day. Time Format String Use the tokens in Table 5-4 when formatting a TIME value. 28) 19 19 95 95 1995 Tuesday a. . first 2 digits with leading zero (century minus 1) Year. last 2 digits.. numeric. Table 5-4 Token %h %0h %t %0t %T Time Format Tokens Description Hour. numeric. numeric. numeric. the result will be unpredictable. Table 5-3 Token %m %0m %M %d %0d %D %j %0j %c %0c %y %0y %Y %W Date Format Tokens Description Month. first 2 digits (century minus 1) Year. ordinal (1st…31st) Day. all 4 digits (0000…9999) Weekday. with leading zero (01…12) Month. if you specify more digits for the token than required.. with leading zero (01…31) Day. numeric. numeric (1…12) Month. with leading zero (00…99) Year.Date and Time Functions Table 5-2 / : . with leading zero (01…366) Year. numeric (1…12) Hour. TIME. numeric (0…999) Millisecond. (zero…fifty-nine) Second. DATE (‘12/1 1998’. numeric (0…59) Minute. INTEGER.1. '%0m/%0d/%0y') TO DATE_VAR MAP DATE ('5-3-99'. ‘%m/%d/%Y’) is invalid because the value of the day token is missing. 1961 was Thursday. DATE (‘12/1998’. TIMESTAMP. Sample Date and Time Functions The following Rules code illustrates the use of most of the date and time functions. word (zero…fifty-nine) Millisecond. with leading zero (00…59) Minute. CHAR (30). It assumes a country specification for the United States and assumes that the current system date and time are 7:26:03 P. with leading zero (00…59) Second. SMALLINT. For example: DATE (‘12/28/1961 Saturday’. DATE (‘12/0/1998’. numeric (0…59) Second. ‘%m/%d/%Y %W’) is invalid because December 28. '%m-%d-%y') TO DATE_VAR AppBuilder 2. with leading zeroes (000…999) Ante (AM) or post (PM) meridiem Example Fourteen 45 45 Forty-five 9 09 Nine 89 089 PM Input String Restrictions Some restrictions apply for input strings when using the DATE and TIME functions: • Input strings must comply to the format string.1 Rules Language Reference Guide 5-15 . ‘%m/%d/%Y’) is invalid because the value of the day token is invalid. ‘%m/%d/%Y’) is invalid because the wrong delimiter is in the input string. 1995. numeric. DATE (‘12/1/98’.. January 26.M. • All token values must be valid for corresponding format string elements (for more information. INTEGER. DCL DATE_VAR TIME_VAR TIMESTAMP_VAR FRACTION_VAR INT_VAR SMALL_INT_VAR CHAR_VAR ENDDCL DATE. MAP DATE ('05/03/99'. numeric. word. • If %W token is specified in the DATE function then weekday must correspond to the date being specified by all the other tokens. numeric. Otherwise -1 is returned as a result. ‘%m/%d/%Y’) is invalid because the year should contain four digits. word (zero…twenty-three) Minute.Date and Time Functions Table 5-4 Token %H %m %0m %M %s %0s %S %f %0f %x Time Format Tokens (Continued) Description Hour. see Table 5-3 and Table 5-4). <* MAP MINUTES (TIME_VAR) TO INT_VAR 5-16 Functions . <* MAP TIME TO TIME_VAR *> Places the value for the system time. the value for 1:22:03 PM into the time <* *> portion. '%t/%m/%s') TO TIME_VAR MAP TIME ('One twenty-two three PM'. '%0m--%0d--%y') TO CHAR_VAR *> Places the value '01--26--95' into char_var. %M %D. TIME_VAR.Date and Time Functions MAP DATE ('Monday. 3 1999 into date_var. <* MAP DAY (DATE_VAR) TO SMALL_INT_VAR *> Places the value 26 into small_int_var. <* MAP CHAR (DATE_VAR. '%h:%0m:%0s %x') TO TIME_VAR MAP TIME ('13/22/3'.99'. they place the value for <* *> 1:22:03 PM into TME_VAR.%y') TO DATE_VAR *> All of these are equivalent. <* MAP CHAR (DATE_VAR. <* MAP DATE TO DATE_VAR *> Places the value for the system date. and the value 0 into the fraction portion. 1995. '%H') TO CHAR_VAR *> Places the value 'Nineteen' into char_var. '%T %M %S %x') TO TIME_VAR *> All of these are equivalent. %Y') TO DATE_VAR MAP DATE ('123. <* MAP TIME ('1:22:03 PM'. FRACTION_VAR) TO TIMESTAMP_VAR *> Places the value for May 3. '%j. 1995' into char_var. <* *> into date_var. <* MAP 0 TO FRACTION_VAR *> Places the value 0 into fraction_var. 7:26:03 PM. 1999'. '%W. <* MAP YEAR (DATE_VAR) TO SMALL_INT_VAR *> Places the value 1995 into small_int_var. <* *> into time_var<* MAP TIMESTAMP TO TIMESTAMP_VAR *> Places the value for system timestamp into timestamp_var. they place the value <* *> for May. <* MAP SECONDS (TIME_VAR) TO INT_VAR *> Places the value 3 into int_var. January 26. %c%y') TO CHAR_VAR *> Places the value 'January/26. <* MAP TIMESTAMP (DATE_VAR. 1999 into the date portion of <* *> the timestamp_var. '%M/%d. <* MAP CHAR (TIME_VAR. May 3rd. <* MAP DAY_OF_YEAR (DATE_VAR) TO SMALL_INT_VAR *> Places the value 26 into small_int_var. <* MAP MONTH (DATE_VAR) TO SMALL_INT_VAR *> Places the value 1 into small_int_var. <* MAP HOURS (TIME_VAR) TO INT_VAR *> Places the value 19 into int_var. format_string ) where: character_expression num_expression Note See “Character Expressions”. See “Numeric Expressions”. except for STRLEN. CHAR with three parameters is available for C mode only. All character functions return a character value. STRPOS. which return an integer. <* MAP INT (DATE_VAR) TO INT_VAR *> Places 728685 (number of days since Jan 1.Character String Functions *> Places the value 26 into int_var. AppBuilder 2. num_expression ) ( character_expression .1 Rules Language Reference Guide 5-17 . 0001) into INT_VAR <* Character String Functions These functions allow you to modify a character string (any valid character value). character_expression ) ( character_expression ) CHAR ( numeric_data_item . <* MAP MINUTES_OF_DAY (TIME_VAR) TO INT_VAR *> Places the value 1166 into int_var.1. and VERIFY. Character String Function Syntax RTRIM UPPER LOWER STRLEN STRPOS VERIFY SUBSTR ( character_expression . num_expression . <* MAP SECONDS_OF_DAY (TIME_VAR) TO INT_VAR *> Places the value 69963 into int_var. size. If the input string is all blanks or null. On some platforms these function can be applied to MIXED and DBCS strings. See Release Specific Considerations. For specific considerations. Characters are converted to upper case according to the specified codepage. and length. The resulting string remains the same type. refer to the following: • UPPER and LOWER in Java • “UPPER and LOWER in ClassicCOBOL” • “UPPER and LOWER in OpenCOBOL” STRLEN This function returns a positive integer that specifies the length of the input string.Character String Functions Function Descriptions RTRIM This function returns the input string with any trailing blanks removed. both single-byte and double-byte trailing blanks are removed. refer to the following: • “RTRIM in Java” • “RTRIM in ClassicCOBOL” • “RTRIM in OpenCOBOL” UPPER and LOWER These functions return the input string with all alphabetic characters converted to uppercase or lowercase respectively. this is true for both single-byte and double-byte. for MIXED strings. See Release Specific Considerations. For DBCS strings. refer to the following: • “STRLEN in Java” • “STRLEN in ClassicCOBOL” • “STRLEN in OpenCOBOL” 5-18 Functions . On some platforms this function can be applied to MIXED and DBCS strings. For additional information. For specific considerations. See Release Specific Considerations. not counting any trailing blanks. STRLEN returns a value of zero (0). For DBCS and MIXED strings. double-byte trailing blanks are removed. it returns its length in characters not bytes. refer to Supported Codepages. On some platforms this function can be applied to MIXED and DBCS strings. For specific considerations. refer to the following: • STRPOS in ClassicCOBOL • STRPOS in OpenCOBOL Position returned by this function measured in characters. dbcs) • VERIFY(mixed. VERIFY This function looks for the first occurrence of a character in the first string that does not appear in the second string. not bytes. char) • STRPOS(dbcs. dbcs) • STRPOS(mixed. Position returned by this function is measured in characters. This function is case-sensitive. The following parameter types are accepted: • VERIFY(char. the position of the first occurrence is returned. If the second string occurs more than once in the first string. See Release Specific Considerations. mixed) • STRPOS(mixed. The following parameter types are accepted: • STRPOS(char.1. dbcs) For specific considerations. dbcs) For specific considerations. If all characters from the first string are found in the second string. The position returned is the number of characters not bytes. The order of characters in the second string and the number of times one of those characters appears in the first string is irrelevant. A zero is returned if the second string is not in the first string.1 Rules Language Reference Guide 5-19 . char) • VERIFY(mixed. refer to the following: • “VERIFY in Java” • “VERIFY in ClassicCOBOL” • “VERIFY in OpenCOBOL” AppBuilder 2. See Release Specific Considerations. On some platforms this function can be applied to MIXED and DBCS strings. On some platforms this function can be applied to MIXED and DBCS strings.Character String Functions STRPOS The STRPOS function searches for a second string in the first string and returns the position from which the second string starts. char) • STRPOS(mixed. This function is case-sensitive. then 0 is returned. char) • VERIFY(dbcs. mixed) • VERIFY(mixed. not bytes. 12 (1234.1) – number enclosed in parenthesis. Java supplies country-specific values.12 -1234 -1234 1234 0 -1234. that character becomes the first character of the resulting substring. Java run-time: Country Germany 9999CR 9999cr 9999cr 9999cr -1234 1234 -1234 1234 -1234 -1234 1234 1234+1234 -1234 + S or s Country specific for C runtime.12) 1234. See Release Specific Considerations.99 999.40 - -9999 -9999 9999+9999 +9999 S9999. descriptions and examples of each are listed in Table 5-5.40 1234. Table 5-5 Symbol 9 $ CHAR Symbols and Descriptions Description Echoes any digit (0-9) Echoes "$" a Echoes any digit (1-9) and removes leading "0".Character String Functions SUBSTR The SUBSTR function returns a substring of the input string that begins at the position the first expression indicates for the length the second expression indicates. Characters that can appear in a format string.99 C run-time: negative number format is set to (1. That is. minus (-) sign is printed for negative numbers Examples 9999.543 1234 Formatted Value 0123.12 1234.12 1234. the first expression is a positive integer that specifies the substring’s starting position in the character string. They are used for Java applications.4 1234.ZZ 123. In this case position and length must specified in characters not bytes. On some platforms this function can be applied to MIXED and DBCS strings.99 $9999 Value 123. Echoes a minus (-) for negative numbers. all the characters are copied from the specified starting position to the end of the string. Trailing zeros that are within the format character range on the right side of the decimal separator will not be suppressed.12 1234.4 123. refer to the following: • “SUBSTR in Java” • “SUBSTR in ClassicCOBOL” • “SUBSTR in OpenCOBOL” CHAR The CHAR function supports conversion from numbers to character strings. The second expression is a positive integer that specifies the number of characters desired in the resulting substring. -1234.12 1234CR 1234cr 1234 0000 CR or cr Negative numbers get "CR" suffix Nothing is printed for non-negative numbers 5-20 Functions . Nothing is printed for positive numbers Prints positive numbers with a plus(+) sign.54 $1234 Z or z ZZZ99. If the second expression is omitted. For specific considerations.12 -1234. they are read from the system for C and from Java settings for Java) Decimal separator (country settings are used) Thousands separator (country settings are used) Examples 9999. the AppBuilder environment determines the length at runtime. In Java. Calling a character function does not change the value of the original character string.50 Any other symbol Echoes the symbol -123.4 1234.99 999.Double-Byte Character Set Functions Table 5-5 Symbol 9 CHAR Symbols and Descriptions (Continued) Description Echoes any digit (0-9) Negative numbers get "DB" suffix Nothing is printed for non-negative numbers "Check protection" character to avoid leading spaces Decimal separator (country settings are used.234.40)) a.30 V or v .30 1.3 1234. For Java specific considerations.1) – number enclosed in parenthesis.4 (~(123.40 1234.54 1234DB 1234db 1234 0000 *123 DB or db * .5 012.999v99 (~S999. 12.99) C run-time: negative number format is set to (1.3 012.99 9999DB 9999db 9999db 9999db **99 Value 123.99 12. see“CHAR in Java” Double-Byte Character Set Functions TheDBCS-enabled versions of AppBuilder also include three (3) functions that cause AppBuilder to treat a character value of one data type as though it were a character value of another data type: • CHAR (character_value) Treats the character value as a CHAR data item • MIXED (character_value) Treats the character value as a MIXED data item • DBCS (character_value) Treats the character value as a DBCS data item AppBuilder 2.1.1 Rules Language Reference Guide 5-21 . 999V99 9. the currency symbol of current locale will be printed. 999. The null string has a length of zero and is denoted with two single quotation marks without an intervening space (''). Most of the character function results do not have a predetermined length. instead.543 -1234 -1234 1234 0 123 Formatted Value 0123. This means that they determine whether or not the argument is actually a valid MIXED or DBCS value according to the specified codepage. each operand can be a variable or a literal of any character type: MIXED. MIXED. However. See DBCS and MIXED Data Types for more information about the use of these data types. For example. See also Comparing Character Values in the Conditions section. then the source can be CHAR. they are verified during the preparation process. 5-22 Functions . CHAR or VARCHAR. then the source can be a variable or literal of any character type. a DBCS variable or literal can only be compared to another DBCS variable or literal. and DBCS in the relational conditions any combination of the operands in the relational condition is allowed. A warning is generated in the case of incompatible types of operands. then the source can be DBCS variable or DBCS literal. If you provide them with a variable.Variables and Literals You can have any character data types as arguments to these functions. You can also use the other character functions with a field of a DBCS or MIXED data type. Variables and Literals ++ (concatenation) Concatenating a string having the value “Cash: ” (with four trailing blanks) with a string having the value “dollars and cents” returns a string having the value “Cash: dollars and cents”. MIXED and DBCS literals are implicitly converted to CHAR data type. that is. If you provide these functions with a string literal. VARCHAR or MIXED variables or a literal of any character type. MIXED. Validation and Implementation Conversion functions MIXED and DBCS perform validations of their arguments. • If the map destination is MIXED variable. they are not checked until execution. and DBCS in a MAP statement: • If the map destination is CHAR or VARCHAR variable. When using variables and literals of CHAR. You will get an exception at runtime if a character string contains DBCS characters. and DBCS Data types When using variables and literals of CHAR. • If the map destination is DBCS variable. MIXED. which are not valid in runtime codepage. you can map the DBCS function applied to any string literal containing a valid DBCS value into a field of type DBCS. For details see: • “Double-Byte Character Set Functions in Java” • “Double-Byte Character Set Functions in ClassicCOBOL” • “Double-Byte Character Set Functions in OpenCOBOL” Using CHAR. 1. SHORTSTRING) returns the integer value 3.Variables and Literals RTRIM Trimming a string having a value "odd integer “odd integer” (no trailing blanks). returns a string having the value UPPER and LOWER UPPER ('12 E 49th Street') = '12 E 49TH STREET' LOWER ('12 E 49th Street') = '12 e 49th street' STRLEN Using STRLEN on a string having a value “CASE Tools ” (with six trailing blanks) returns the integer value 10. " (five trailing blanks). AppBuilder 2.1 Rules Language Reference Guide 5-23 . which is the last non-blank position in the character string. then STRPOS (LONGSTRING. STRPOS If the value of LONGSTRING is “A short string in the long string” and the value of SHORTSTRING is “short string”. which is the position in LONGSTRING that contains the first character of SHORTSTRING. The error code is set for arithmetic operations (division by zero. which is the position of the M. NUMBERS_AND_SPACE) returns the position of the first character in the indicated string that is not a number or space. In this case. then VERIFY ('8000 Main Street'. numeric overflow. for memory allocation problems. If the value is 0.3. for method invocations of AppBuilder-supplied window objects.Error-Handling Functions VERIFY If the variable NUMBERS_AND_SPACE is “0123456789 ” (containing a space after the 9). Error-Handling Functions Three functions can be used to analyze errors during program execution: • HPSError Function • Reset Error Function • Error Message Function See “Target Language Support Tables” for restrictions. then no error occurred.12) returns a string having the value “substring in”. Otherwise. the integer value 6 is returned. the value is the error code of the first error that occurs. and so on). SUBSTR If the value of LONGSTRING is “A substring in the long string”. which includes the twelve characters starting at the third position in LONGSTRING. HPSError Function The HPSError function returns an integer value. do the following: 5-24 Functions . then SUBSTR (LONGSTRING. To check for an error. and for some other run-time errors. this function returns the same value.1 Rules Language Reference Guide 5-25 .1. Support Functions These miscellaneous functions support various features of AppBuilder. If an error description is not found. See “Java Extensions” for more information. Refer to the Messages Reference Guide for a list of the error codes returned by HPSError. then the error code corresponds to the first error that occurred. Error Message Function The HPSErrorMessage function takes an error code as an argument and returns the text string containing a short description of the error condition. Until the error code is reset with HPSResetError. Reset Error Function The HPSResetError function resets the error code to 0 after one or more error conditions have occurred. AppBuilder 2.Support Functions IF HPSError <> 0 PERFORM ErrorHandler ENDIF If there are several errors. along with the associated text strings returned by HPSErrorMessage. along with the associated text strings returned by HPSErrorMessage. then the string is empty. Refer to the Messages Reference Guide for a list of the error codes returned by HPSError. scale) DATE 5-26 Functions . Table 5-6 Data Type BOOLEAN SMALLINT INTEGER PIC (signed) a See “Character Expressions”. See “Expression Syntax”. SIZEOF Built-in Function Values by Platform Table 5-6 lists the sizes of each Rules Language data type. expression character_expression ) . Platform-specific Data Type Sizes C 2 2 4 Length+1 Length Length+1 4 Java 2 2 4 Length+1 Length Length+1 4 ClassicCOBOL 2 2 4 Length+1 Length (Length+1) div 2 4 OpenCOBOL 2 2 4 Length+1 Length (Length+1) div 2 10 PIC (unsigned)a DEC(length. ISNULL CLEARNULL ( ( field field view ) ) SET_ROLLBACK_ONLY GET_ROLLBACK_ONLY where: character_expression expression view SIZEOF This function takes a view as an argument and returns its data length in bytes in a field of type INTEGER. See “View”. language ) ( view ) expression .Support Functions Support Functions Syntax SIZEOF LOC HIGH_VALUES LOW_VALUES SETDISPLAY SETENCODING TRACE ( ( ( set_name set_name . . and several HPS_BLOB components. Although designed for the mainframe LOCATE I/O mode system components.Using LOC Function in Java Mode” HIGH_VALUES The HIGH_VALUES represents one or more characters that have the highest ordinal position in the collating sequence used and is useful for initializing database fields or for comparisons. you can use it in all operating environments. Example .Using HIGH_VALUES Function MAP HIGH_VALUES TO HI_CHAR_FIELD LOW_VALUES The LOW_VALUES represents one or more characters that have the lowest ordinal position in the collating sequence used and is useful for initializing database fields or for comparisons. Length is the number of digits in PIC’s storage picture.1 Rules Language Reference Guide 5-27 . For Java specific considerations. you can map its value only to a field of type CHAR or VARCHAR.Using LOW_VALUES Function MAP LOW_VALUES TO LO_CHAR_FIELD AppBuilder 2. Although designed for the mainframe LOCATE I/O mode system components. see “LOC in Java” and“Example . It is used in conjunction with the following system components: HPS_READ_FILE_LOCATE_MODE.Using SIZEOF Function MAP SIZEOF (VIEW_1) TO SIZE_LONG OF HPS_READ_FILE_LOCATE_MODE_I LOC The LOC function takes a view as an argument and returns its location in a CHAR (8) field.1. For example.Support Functions Table 5-6 TIME Platform-specific Data Type Sizes (Continued) 4 12 256 256 4 Length Length+2 Length*2 Length 4 12 256 256 4 Length Length+2 Length*2 Length 4 12 256 256 Length Length+2 Length*2 Length 12 26 256 256 Length Length+2 Length*2 Length TIMESTAMP TEXT IMAGE OBJECT CHAR(length) VARCHAR(length) DBCS(length) MIXED(length) VIEW Sum of SIZEOF applied to each view field a. Example . the length of PIC ‘S999V99’ is 5. Example . you can use it in all operating environments. you can map its value only to a field of type CHAR or VARCHAR. However. MAP LOC (VIEW_1) TO LOCATE_RECORD OF HPS_READ_FILE_LOCATE_MODE_I See the System Components Reference Guide for more information. HPS_WRITE_FILE_LOCATE_MODE. However. ClassicCOBOL. Since this function looks for an identical value. and OpenCOBOL modes. STATE_NAME) TO STATE_CODE 5-28 Functions . For additional considerations see: • “SETDISPLAY in ClassicCOBOL” • “SETDISPLAY in OpenCOBOL” Note This function is not supported on UNIX and AS/400 servers. Example . 1) TO DBCS_VAR DBCS(RTRIM(CHAR_VAR)) TO DBCS_VAR SETENCODING The SETENCODING function supports the use of sets. This argument defaults to the language entity of the active process.If it does not find the encoding. If it does not find the display. ClassicCOBOL. The last argument is needed only for an MLS (Multiple Language Support) application and is the language entity to use for getting the representation of the encoding (the second argument). the second argument can be MIXED or DBCS also. In Java. If that set is an INTEGER (31) set. 1) TO CHAR_VAR MIXED(CHAR_VAR) TO MIXED_VAR SETDISPLAY (DBCS_SET. You can use the corresponding conversion function to treat the returned value as a MIXED or DBCS value. it returns zero (0) for a numeric set and all spaces for a character set. MIXED with different types of trailing spaces or shift characters sequences will be considered non-equal and SETENCODING will not find the corresponding encoding. Its first argument is the name of a Lookup Table set. This argument defaults to the language entity of the active process. the lookup value can be MIXED or DBCS.Using SETDISPLAY Function with MIXED and DBCS Sets MAP MAP MAP MAP SETDISPLAY (MIXED_SET. Since this function looks for an identical value.Support Functions SETDISPLAY The SETDISPLAY function supports the use of sets. Its second argument is the value to look up in the set and must be of the correct type for that set. SETENCODING returns a value of the same type and length as the set in first argument. This function returns a value in a CHAR (80) field even if SET was MIXED or DBCS. the function will return an INTEGER (31) value. Its second argument is the representation to look up in the set and can be any valid character value. ClassicCOBOL. In Java.Using SETDISPLAY Function MAP SETDISPLAY (STATES_IN_US. The last argument is needed only for an MLS application and is the language entity used for getting the display (the second argument). Example . and OpenCOBOL modes. and OpenCOBOL modes. 1) TO STATE_NAME MAP SETDISPLAY (STATES_IN_US. Note This function is not supported on UNIX and AS/400 servers. In Java. the representation value can be MIXED or DBCS. OHIO IN STATES_IN_US) TO STATE_NAME Example . MIXED with different types of trailing spaces or shift characters sequences will be considered non-equal and SETDISPLAY will return all spaces. it returns all spaces. Its first argument is the name of a Lookup Table set.Using the SETENCODING Function MAP SETENCODING (STATES_IN_US. ‘OHIO’) TO STATE_CODE MAP SETENCODING (STATES_IN_US. 1 Rules Language Reference Guide 5-29 .1. If the view is output to trace. views. ENDDCL MAP 27 TO I TRACE(I) *> Outputs TRACE(I+3) *> Outputs TRACE(V) *> Outputs TRACE(I. along with their values are output as well. field names. Example . See also “TRACE in Java” and “Restrictions in ClassicCOBOL”. I+1) *> Outputs “27” <* “30” <* “Field I: 30” <* “27 28” <* AppBuilder 2. it cannot be used inside an expression. occurring views. Fields.Support Functions TRACE TRACE function can be used to output Rules data items to an application trace. and results of any expressions can output to a Java application trace.Using TRACE Function DCL I INTEGER. The trace is output only if the Rule debug option in the Construction Workbench > Options > Preparation tab is selected. The TRACE function has no return value and therefore. V VIEW CONTAINS I. Support Functions 5-30 Functions . 1 Rules Language Reference Guide 6-1 .1.CHAPTER 6 DECLARATIONS AppBuilder 2.1.1 Rules Language Reference Guide Use a declarative statement (DCL) to declare a: • Local Variable Declaration • Local Procedure Declaration • Event Procedure Declaration Other relevant topics include: • Using Entities with Equal Names • Choosing and Setting Signatures • Using System Identifiers • Using System Identifiers • PRAGMA CLASSIMPORT for Java • PRAGMA CLASSIMPORT for Java • Setting Number of Occurrences (Right-Side Subscript) • Setting Number of Occurrences (Left-Side Subscript) • Controlling Compile Time Subscript • Preparing a Rule Declaration Declaration Syntax DCL local_variable local_procedure event_procedure ENDDCL AppBuilder 2. 6-2 Declarations . where local_variable is: . If you use a DCL statement inside a procedure. Variable qualification (both OF and dot specification) cannot be used in LIKE clause.Local Variable Declaration Local Variable Declaration Use a DCL statement to declare a variable data item or view locally. For usage information. then any use of the name inside the procedure refers to the local variable and not to the variable existing outside the procedure. or inside a procedure to declare variables local to the procedure. A variable declared in a DCL statement is not contained in the repository. if a name is declared inside a procedure but also occurs outside the procedure. Usage Use a DCL statement at the beginning of a rule to declare variables local to the rule. That is. the variable is local to the procedure even if the same name occurs elsewhere in the rule. either locally or in any subview. VIEW CONTAINS variable_data_item view_name where: data_type variable_data_item Note See “Data Types”. See “Variable Data Item”. view_name LIKE view_name . An item_name or a view_name cannot start with the underscore symbol (_). so it is not available to any rules or components the declaring rule uses. review the following sections: • Usage • Valid Data Types • Using LIKE Clause • Using VIEW CONTAINS Clause Local Variable Syntax local_variable . item_name data_type LIKE variable_data_item . the name of a locally-declared variable must not duplicate the name of any other variable in the rule’s data universe. If you use a DCL statement at the beginning of a rule. Local Variable Declaration You can have zero, one, or many DCL statements in a rule or procedure, but they must precede all other statements in that rule or procedure. The DCL statement sets aside a temporary area of memory storage for use only during the declaring rule’s execution. When a rule or procedure is invoked, all locally declared fields are cleared (for example, character fields are set to the null string and numeric and date and time fields are set to 0). The reasons you might want to declare a data item locally include: • Storing temporary data, such as during a swap procedure • Breaking up data (for example, if you need only part of an employee record—say, the employee number—from a record in a flat file) • Adjusting the size of a list box to reflect the number of records it contains Valid Data Types Valid data_types for use in a variable declaration include: • character_data_type • numeric_data_type • data_and_time_data_type • object_data_type • boolean_data_type • large_object_data_type For a description of data_types, see Chapter 2, “Data Types” Using LIKE Clause Use the LIKE keyword locally to define a field to be identical to another field in the rule’s data universe, or a view to be identical to another view in the rule’s data universe. Any variable after LIKE must have been declared previously, either locally or in a subview in the rule hierarchy, except the name of the new local variable. If you declare a data item locally as being LIKE another, you can use the local data item exactly as you can use the original, but only within the declaring rule. A view declared locally has the same subviews and fields as the original view. A view declared with a LIKE clause can be subscripted so that it is multiple-occurring; a field cannot be subscripted. Example - LIKE Keyword in DCL Statement DCL COUNTER_1,COUNTER_2 SMALLINT; SUBTOTAL INTEGER; NAME_TEMP CHAR(30); ITEM_CODE VARCHAR (20); PRICE DEC (6,2); SHOW_PRICE PIC '9999V99'; DATE_OF_PURCHASE DATE; TIME_OF_PURCHASE TIME; CUSTOMER_TEMP (20) LIKE NAME; *> NAME is a view declared in rule hierarchy <* ENDDCL AppBuilder 2.1.1 Rules Language Reference Guide 6-3 Local Procedure Declaration This DCL statement creates nine local fields and one local view. Each field can be used in the rule’s code exactly as if it were a field entity of that type in the rule’s data universe. CUSTOMER_TEMP is declared LIKE NAME and is also declared as occurring 20 times. You can use it in the rule’s code exactly as if it were a multiple-occurring view with the same subviews and fields as the NAME view. You do not have to qualify the view name to specify one instance of NAME, because you are referring to the single definition of the view in the repository. Note that if NAME is declared as a (sub)view, then the code is syntactically correct. If NAME is a field, the rule’s preparation results in a syntax error because CUSTOMER_TEMP, as shown above, is subscripted and a field cannot be subscripted. Using VIEW CONTAINS Clause Note As discussed in “Variable Data Item”, you may omit the names of some of a field’s ancestral views in a statement. However, you must always include the occurrence number of a multiple-occurring subview in a statement even if the view’s name does not appear. Use a VIEW CONTAINS clause to build a local view from lower-level views and fields. Building a local view with this clause is equivalent to building a View includes Field or View includes View relationship in a repository. Unlike the name of the new local variable, any variable after VIEW CONTAINS must have been declared previously, either locally or in a subview. Thus, local declaration of views is “bottom up” or “inside out.” All the identifiers to the left of VIEW CONTAINS represent views, each of which relates to each of the field or subview entities to the right of VIEW CONTAINS. Order is important when building a view locally, just as it is when building a view within the repository. The order in which the elements appear indicates their position in the view’s hierarchy, with left most element being the highest in the hierarchy, down to the right most, which is lowest. However, the order in which those fields and subviews were originally built does not matter, as long as they exist before you attempt to relate them to the higher-level view. A VIEW CONTAINS clause has a parent view on the left and a child view or field on the right. Local Procedure Declaration Declaration of a local procedure in a DCL statement is useful if the procedure might be used before it is defined. For example, consider two procedures that call each other: the first one calls the second which is not defined, its definition located below the first procedure. This situation can be resolved by declaring the second procedure in a DCL statement of the rule. The declared procedure must be defined somewhere in the rule (where the procedure definition is allowed). See Common Procedure in Chapter 7, “Procedures” for the syntax diagram and description of a procedure. 6-4 Declarations Local Procedure Declaration Local Procedure Syntax local_procedure ; proc_name PROC parameter_list : output_type where proc_name is the name of a procedure to be declared, and where parameter_list is: , parameter_name data_type LIKE field_name and for data_type, refer to Chapter 2, “Data Types”. Note An proc_name or a parameter_name cannot start with the underscore symbol (_). The output type can be any data type, except objects. Alias declaration can never be used as a procedure formal parameter. For additional information on procedure parameters, see “Local Procedure Declaration in Java”. Example - Declared Procedure DCL *> Procedures declaration <* PROC1 PROC(I INTEGER); PROC2 PROC(I INTEGER) : INTEGER; ENDDCL PROC1(10) *> Procedures definition <* PROC PROC1(I INTEGER) DCL Result INTEGER; ENDDCL MAP PROC2(I) TO Result PRINT Result *> "100" is printed <* ENDPROC PROC PROC2(I INTEGER) : INTEGER PROC RETURN(I*I) ENDPROC AppBuilder 2.1.1 Rules Language Reference Guide 6-5 Event Procedure Declaration Event Procedure Declaration An event procedure is invoked when an event you have chosen to respond to is triggered for an object. For a list of available events, see the ObjectSpeak Reference Guide. Event Procedure Syntax event_procedure ; proc_name PROC FOR event_name LISTENER listener_name OBJECT TYPE object_name ‘class_identifier’ object_type OF subsystem where: proc_name event_name listener_name ... is: name of a procedure to be declared the name of the declared object event the name of the interface that implements event triggering (Java only) any of: • The system identifier (HPSID) of the object • The alias of the object (see “Object Data Items”) • A pointer to the object (see “Object Data Types”) a string that identified the class. It might be CLSID or OLE objects or fully qualified class name for Java classes. The identification string is considered case-sensitive. is the type of the object whose event(s) the procedure receives. See Object Types. the group that the object belongs to. The following are supported: • GUI_KERNEL, the set of window controls supplied with AppBuilder • JAVABEANS, for any Java class object_name class_identifier object_type subsystem Note An proc_name cannot start with the underscore symbol (_) Object Types An object_name cannot be the same as an AppBuilder predefined object_type name. A full list of object_type names can be found in the ObjectSpeak Reference Guide. 6-6 Declarations Event Procedure Declaration Usage You must define an event procedure inside the rule that converses the window containing the objects whose events the procedure responds to. See “Event Handling Procedure”. For more details about the automatic handler assignment, see the Event Handler Statement in Java description. A DCL statement is not necessary to define an event procedure. Use a DCL statement to specify the same procedure for multiple events, objects, or object types. For example, suppose the following procedure is defined in a rule: PROC clickControl ... ENDPROC Given this procedure and the appropriate DCL statement, you can use the procedure for: • One Event Procedure for Multiple Events (for multiple events of the same object) • One Event Procedure for Multiple Objects • One Event Procedure for Multiple Object Types • LISTENER Clause (Java only) One Event Procedure for Multiple Events If you want the same procedure to handle the Click and DoubleClick events for the same object, include the following DCL statement at the beginning of the rule that contains the procedure: DCL clickControl PROC FOR Click OBJECT myListBox; clickControl PROC FOR DoubleClick OBJECT myListBox; ENDDCL One Event Procedure for Multiple Objects Similarly, if you want the same procedure to handle an event for multiple objects, include the following DCL statement at the beginning of the rule: DCL clickControl PROC FOR Click OBJECT myListBox; clickControl PROC FOR Click OBJECT myPushButton; clickControl PROC FOR Click OBJECT myRadioButton; ENDDCL One Event Procedure for Multiple Object Types If you want the same procedure to handle an event for multiple object types, include the following DCL statement: DCL clickControl PROC FOR Click TYPE ListBox; clickControl PROC FOR Click TYPE PushButton; clickControl PROC FOR Click TYPE RadioButton; ENDDCL AppBuilder 2.1.1 Rules Language Reference Guide 6-7 Using Entities with Equal Names LISTENER Clause The LISTENER clause is only available for Java. Use the LISTENER clause to avoid conflicting situations when an object has two events with the same name. Note If an object has no conflicting events, this clause may be omitted. See also “Example - Java LISTENER Clause”. Using Entities with Equal Names It is possible to have several different entities with the same name in a rule scope. However, in that case, one entity may hide another (make that entity unusable in a rule). In some cases, when names of entities are the same, it is clear from the syntax which of the two must be used. For example, if there is a procedure and a field with the name I, and there is a procedure call, it is clear that a procedure must be used instead of a field, as shown in the example which follows. AppBuilder follows the order of precedence in Table 6-1. Table 6-1 Order 1 2 3 4 Entity Precedence Entities Fields, views, sets and set symbols Procedures Rules Window object, Rule object, System identifier (HPSID), MENUITEM, Set Object Example - Entities Using the Same Name DCL I, J INTEGER; ENDDCL PROC I : INTEGER *> ...some code... <* ENDDPROC MAP 1 TO I *> Variable <* I *> Procedure (return value is lost) <* MAP I TO J *> Variable (according to order of precedence) <* PERFORM I *> Procedure (return value is lost) <* In general, if two entities have the same order of precedence, their names must not coincide. For example, it is an error to have both a view and a field with the name I. If two entities have the same name and their order of precedence is not equal, the one that is higher in the order is selected. 6-8 Declarations and qualification (of view name). IMAGE DBCS MIXED DATE TIME TIMESTAMP OBJECT To distinguish between fields and set symbols with the same name. ENDDCL PROC I(D DATE) *> This procedure is visible – it has a different signature with variable I <* . field. V VIEW CONTAINS I.1 Rules Language Reference Guide 6-9 .Choosing and Setting Signatures Choosing and Setting Signatures When choosing between field and procedure or between different procedures. or view. ENDPROC PROC V1(I INTEGER) *> This procedure is visible – as view V1 does not have subscripts it has a different signature with this procedure <* AppBuilder 2. list of occurrence indices. Two signatures are equal if names and number of parameters are equal. See Table 6-2 for a list of compatible types. names and signatures are compared to each other. Table 6-2 List of Compatible Parameter Types Parameter Types INTEGER. a qualification can be used. Types listed on the same row are compatible. set symbol. The set symbol signature is its name and qualification (in set name). PIC CHAR.. it is possible to use a field with the same name as a set symbol in an external view created in a Hierarchy diagram. To distinguish between procedure. Examples Example .Choosing and Setting Signatures DCL I INTEGER. SMALLINT DEC.. V1 VIEW CONTAINS V(10). Note Although you cannot declare a local variable with the same name as a set symbol. a different parameter type can be used. parameter types are compatible. and qualifications are the same.1. The signature of a procedure is its name and list of parameters. TEXT. A signature of a field or view is its name. VARCHAR. .1)) : INTEGER .Ambiguity Error *> Hierarchy: Set K Value J Value L Value M View IO_VIEW 6-10 Declarations .1) TO SomeVariable *> Here the return value of V1(DEC) * is mapped to SomeVariable <* Note that in this example it is impossible to use the return value of procedure V1. in procedure call V1(27) it is impossible to distinguish which one is meant <* PERFORM V1 *> Procedure V1 without parameters is called – * variable can not be used in PERFORM * clause <* V1 *> Procedure V1 without parameters is called – variable can not occur here <* V1(0) *> V1(INTEGER) is called... ENDPROC PROC V1(D DEC(10. because argument is integer <* V1(0..2)) *> * * * * This causes a compile error: V1(DEC(10. * according to order of precedence. ENDPROC PROC V1 : INTEGER .. ENDPROC *> This procedure conflicts with view V1 – * see examples below on how to use it <* PROC V1(D DEC(10. Example . in procedure call V1(1. ENDPROC This causes a compile error: V1(INTEGER) may not be redefined for example. * not return value of procedure V1 <* MAP V1(1. ENDPROC PROC V1(SI SMALLINT) *> * * * * ..1)) may not be redefined for example..0) *> V1(DEC) is called because argument is decimal <* MAP V1 TO SomeVariable *> View V1 is mapped to SomeVariable.1) it is impossible to distinguish which one is meant <* ..Choosing and Setting Signatures ... *> Incorrect – same name as set symbol <* I. J IN K) TO DISPLAY *> OK <* Using System Identifiers The system identifier (HPSID) that coincides with a name of some other entity is always hidden. • WINDOW of GUI_KERNEL • RULE of GUI_KERNEL • Other object type • MENUITEM of GUI_KERNEL AppBuilder 2. K INTEGER. but other Rules identifiers are not. V2 VIEW CONTAINS I. the object with this HPSID can still be used.1 Rules Language Reference Guide 6-11 . L INTEGER. -2) TO I OF V2 *> OK <* MAP SETDISPLAY(K. Note The system identifier (HPSID) is case-sensitive. if an alias is declared for this HPSID using an OBJECT ‘HPSID’ DCL statement clause. If there are two system identifiers (HPSIDs) with the same name or their names differ only in case. -2) TO I OF V1 *> OK – set K can not be used in ROUND. K. However. V1 VIEW CONTAINS I. *> Incorrect – can’t distinguish between set symbol and local variable <* DISPLAY CHAR(10). The one that can be used is chosen according to the following list (the system identifier in upper case is chosen).1. ENDDCL MAP 1 TO I *> MAP 27 TO I OF V1 *> MAP 15 TO M *> * Ambiguity error – I OF V1 or I OF V2? <* OK <* OK – M is a variable. so this * line is equal to the next line <* MAP ROUND(K OF V2.Using System Identifiers Field M <* DCL J INTEGER. so a system identifier that differs with some other identifier only in case is considered to coincide with that identifier. only one of them can be used in a rule. set symbol cannot be used here <* MAP 15 TO M OF IO_VIEW *> OK <* MAP M TO I OF V2 *> Ambiguity error – set symbol M or J OF V1?<* MAP M IN K TO I OF V2 *> OK – M is a set symbol <* MAP M OF IO_VIEW TO I OF V2 *> OK – I is a field <* MAP K TO I OF V1 *> OK <* MAP I OF V1 TO K *> OK <* MAP ROUND(K. I(0) doesn’t exist. The rule also contains VIEW_2. Caution Subscript control at compile time does not perform in Java because of dynamic views support. (Refer to the Error Messages Reference Guide for descriptions of error messages). The rule does not prepare correctly unless FLD1 and FLD2 already exist in the rule’s data universe. 3) fields. VARCHAR (6).Controlling Compile Time Subscript Controlling Compile Time Subscript At compile time. CHAR_2 VARCH_1 PIC_1 DEC_1 VIEW_1 CHAR. VARCH_1 is a VARCHAR field of (maximal) length 6. which themselves are declared as CHAR (1) fields. Example . which consists of PIC_1 and DEC_1 defined as PIC 'S999V99' and DEC (9. of VIEW_1. Refer to the subscript control sections of arithmetic type chapters you are currently using (“Decimal Arithmetic Support”) for a description of run-time behavior if the subscript is out of range. subscript is less than one <* MAP 0 TO INDX MAP 1 TO I(INDX) *> Run-time error <* Preparing a Rule Declaration In the example of a local rule declaration below. VIEW_4. PIC 'S999V99'.Subscript Control DCL I INTEGER. of VIEW_2. A constant subscript less than one. VIEW_6 is a view that consists. ENDDCL MAP 1 TO I(0) *> Compile time error. causes a preparation error. Sample Local Rule Declaration DCL CHAR_1. DEC (9. it cannot be verified at compile time. Views VIEW_3. VIEW CONTAINS CHAR_1. INDX INTEGER. 3). among other items. subscript control is performed for all constant subscripts in the rule. CHAR_2. V(10) VIEW CONTAINS I. which occurs 10 times within VIEW_6. each consists of FLD1 followed by FLD2. Note The sample declaration in the example below contains implied qualifications. or greater than view size. and of VARCH_1. If the subscript expression contains a variable data item. and VIEW_5 are all constructed the same way. 6-12 Declarations . VIEW_1 consists of CHAR_1 and CHAR_2. .VIEW_1. ENDDCL is equivalent to: DCL VIEW_7 LIKE VIEW_1. VARCH_1.Preparing a Rule Declaration *> Note the "Inside out" principle: The building blocks CHAR_1 and * CHAR_2 must have been declared before the containing view VIEW_1 * can be declared <* VIEW_2 VIEW CONTAINS PIC_1.. VIEW CONTAINS . They exist only as subviews of VIEW_6. VIEW_1. The first MAP statement is now invalid because it is not clear whether CHAR_2 refers to CHAR_2 OF VIEW_1 OF VIEW_6 or to CHAR_2 OF VIEW_7. AppBuilder 2. In addition. VIEW_5 VIEW_6 ENDDCL In this example. DEC_1.. VIEW_4. qualify a name. the following statement in the rule: MAP VARCH_1 TO CHAR_2 is interpreted as: MAP VARCH_1 OF VIEW_6 TO CHAR_2 OF VIEW_1 OF VIEW_6 In other words.VIEW_2 (10).. CHAR_2... Fld2.. . VIEW_3. or VARCH_1 that exist by themselves.1. To avoid this kind of ambiguity.1 Rules Language Reference Guide 6-13 . CHAR_2 OF VIEW_6 is acceptable. there are no local variables CHAR_2.. VIEW CONTAINS Fld1. For example.. ENDDCL assuming that this declaration is made after that of VIEW_1. the following declaration: DCL VIEW_7 VIEW CONTAINS CHAR_1.. if you assume that the last declaration is X (3) VIEW CONTAINS P (4). ENDDCL A is not used as a building block and you can reference A(1). you can qualify P of X (m. the left side subscripting P(5) is again ignored. n) where 1 <= m <= 3 and 1 <= n <= 4. it cannot be a field. If this happens. P is used as a building block for X. View A consists of ten occurrences of View B: DCL A VIEW CONTAINS B (10). However. Example: Assume that the following constitutes all local declarations for a rule. A(2). X (3) VIEW CONTAINS P. ENDDCL Setting Number of Occurrences (Left-Side Subscript) A subscript on the child view or field indicates the number of times that view or field occurs within the parent view only if this left side parent view does not itself become a building block for a higher-level view. 6-14 Declarations . you are not prompted with a syntax error but subscripts are ignored.…. but the right side subscripting P(4) is not.Preparing a Rule Declaration Setting Number of Occurrences (Right-Side Subscript) A subscript on the child view indicates the number of times that view occurs within the parent view. X(2). so you cannot subscript P five times. P (5) VIEW CONTAINS B. The child in this case can be a view only. DCL A (7) VIEW CONTAINS B. X is not used as a building block and you can reference X(1). X(3). In the following example. In this situation. A(7). 1 Rules Language Reference Guide 6-15 .Preparing a Rule Declaration AppBuilder 2.1. Preparing a Rule Declaration 6-16 Declarations . Procedure Syntax common_procedures event_procedures error_procedures Common Procedure You can define a procedure anywhere within a rule except within another procedure body.1 Rules Language Reference Guide A procedure is defined using the PROC and ENDPROC keywords. Common Procedure Syntax PROC common_procedure proc_statements ENDPROC where proc_statements are: DCL_local_variable statement where common_procedure is: AppBuilder 2. However.CHAPTER 7 PROCEDURES AppBuilder 2. A procedure can consist of any number of Rules Language statements. You can define a: • Common Procedure to encapsulate portions of code.1. a natural placement for a procedure definition is near the top of a rule. because a procedure must be defined before you can invoke it. See “PERFORM Statement” for information on invoking a procedure.1. • Event Handling Procedure to respond to events from objects.1 Rules Language Reference Guide 7-1 . You can invoke a procedure only in the rule in which the procedure is defined. parameter_name . statement Note Usage You can pass individual data items. or literals. The four examples shown below illustrate how to use common procedures.Common Procedure procedure_name . For additional information on common procedure parameters. except objects. If one of the procedure’s parameters is a view that was not declared through the LIKE clause. Any Rules Language statement. the view must also be declared in the rule DCL section or exist within the rule data hierarchy. If the procedure returns a value. except procedure declaration. See “Local Variable Declaration”. it must be declared in the procedure. Examples . The output type can be any data type. Alias declaration can never be used as a procedure formal parameter. If the procedure returns a view. the procedure is treated like a function and can be used in any context in which a function can be used (see Example 2 Using a Procedure as a Function).Common Procedures 7-2 Procedures . the view must be declared inside the procedure receiving it (see Example 3 . view_name data_type LIKE LIKE field_name view_name where output_type can be: data_type LIKE variable_data_item view_name where: data_type DCL_local_variable variable_data_item See Chapter 2. as parameters to procedures. ( parameters ) : output_type where parameters can be: . including a view. A procedure can return a value. “Data Types”. see “Defining Views in Java” and“Common Procedures in C”. If you pass a view to a procedure. See “Variable Data Item”.Passing a View to a Procedure). Note that you cannot have OBJECT ARRAY as a parameter. commissions DEC(31.Passing a View to a Procedure The procedure returns a numeric value: PROC getTaxableIncome (income VIEW): DEC(31.Common Procedure Example 1 . ORDER_NO INTEGER. PROC handleError(errorCode SMALLINT) DCL errorDescr VARCHAR(255).commissions. handleError(code) .1 Rules Language Reference Guide 7-3 . bonus. handleError(dbCode) Example 2 . AppBuilder 2.2).Using a Procedure as a Function The procedure “cubed” receives one parameter (an integer) and returns the cube of that number. PROC cubed (inputNumber INTEGER): INTEGER PROC RETURN (inputNumber * inputNumber * inputNumber) ENDPROC .Returning a View from a Procedure DCL CUSTOMER_NAME CHAR(30). ENDDCL PROC RETURN (baseSalary + bonus + commissions) ENDPROC . ENDDCL IF errorCode <= 0 MAP "SUCCESS" TO errorDescr ELSE IF errorCode <= 2 MAP "WARNING" TO errorDescr ELSE MAP "SEVERE ERROR" TO errorDescr ENDIF ENDIF PRINT errorDescr ENDPROC . MAP getTaxableIncome(income) * taxRate to tax Example 4 .2).1. MAP cubed(anyNumber) to y Example 3 . the coding of each process is simplified.bonus. income VIEW CONTAINS baseSalary.Simplifying Error Code Processing By defining a procedure with code common to multiple error code processing. The procedure can be used in any context in which a function can be used—in this case in a MAP statement.12) DCL baseSalary DEC(31. Event Handling Procedure ORDER_RECORD VIEW CONTAINS CUSTOMER_NAME. LAST_NO }) ENDPROC Event Handling Procedure There are two ways to handle events: • Event Procedures • HPS_EVENT_VIEW Method Related information includes: • Event Parameters • Specific Restrictions for “Constructing an Event Handler in C” • Specific considerations and restrictions for “Constructing an Event Handler in Java” Event Procedure Syntax PROC event_procedure proc_statements ENDPROC where event_procedure is: proc_name FOR event_name OBJECT object_name TYPE object_type OF subsystem . ENDDCL PROC CREATE_ORDER(NAME CHAR(30)) : LIKE ORDER_RECORD DCL V LIKE ORDER_RECORD. parameters 7-4 Procedures . LAST_NO INTEGER. ORDER_NO. LAST_NO MAP NAME TO CUSTOMER_NAME OF V PROC RETURN (V) ENDPROC PROC NEW_ORDER(V LIKE ORDER_RECORD) : LIKE ORDER_RECORD MAP LAST_NO + 1 TO LAST_NO PROC RETURN ({ CUSTOMER_NAME OF V. ENDDCL MAP LAST_NO + 1 TO ORDER_NO OF V. see the ObjectSpeak Reference Guide. You must write a procedure for an event to be handled.1. When the event procedure finishes (or when a PROC RETURN statement is encountered) the rule continues conversing the window.Event Handling Procedure where: can be: any of: • The HPSID of the object object_name • The alias of the object (see “Object Data Items”) • A pointer to the object (see “Object Data Items”) data_type variable_data_item parameters proc_statements object_type subsystem See “Data Types”. See “Common Procedure”. Control does not return to the statement following the CONVERSE until an event is returned in HPS_EVENT_VIEW. AppBuilder 2. event procedures are supported only for AppBuilder-supplied window objects in Java. See “Common Procedure”. Currently. An event procedure is invoked when an event is triggered for an object. The following subsystems are supported: • GUI_KERNEL is the set of AppBuilder-supplied window controls. Event Procedures To use an event procedure. See “Variable Data Item”. Note It is necessary to specify a subsystem only if there is an ambiguity. This includes any event triggered by AppBuilder-supplied (GUI_KERNEL) window control. include it in the rule that converses the window.1 Rules Language Reference Guide 7-5 . test the contents of HPS_EVENT_VIEW in statements following the CONVERSE statement. waiting for another user event to occur. • JAVABEANS is used for any Java class. the type of object whose event(s) the procedure receives the group to which the object pointed to belongs For a list of available object types. Do not use Window Painter to select the events to be handled. To handle events from AppBuilder-supplied window objects in C mode. ENDPROC Example .Handling a Particular Event of a Type of Object The following procedure can be defined to handle the Initialize event for any Window control: 7-6 Procedures .Event Handling Procedure You must define an event procedure inside the rule that converses the window containing the Java objects whose events the procedure responds to. converted to a character string and separated by commas Event Parameters Many events include parameters. To do the things that are not allowed in an event procedure.Defining a Particular Event of a Particular Object The following procedure can be defined to handle the Initialize event of a Window control named MY_WINDOW: PROC windowInitialize FOR Initialize OBJECT MY_WINDOW (p OBJECT TYPE InitializeEvent) .Setting Event Parameters Example . refer to the ObjectSpeak Reference Guide. To see what parameters are returned to an event procedure when the event is triggered... the following information is returned in HPS_EVENT_VIEW: • EVENT_SOURCE: The HPSID of the control • EVENT_QUALIFIER: The name of the event • EVENT_PARAM: The parameters returned by the event. The following two examples show how to define and handle specific events for specific objects. HPS_EVENT_VIEW Method The HPS_EVENT_VIEW method is supported only for consistency with the way events are handled for AppBuilder-supplied window controls. When an event is triggered. Examples . you can invoke the ThisRule’s PostEvent method (see “Java Values and Conversions”) to return control to the rule at the statement following the converse. except : • CONVERSE • USE RULE • USE COMPONENT • POST EVENT • PERFORM You cannot modify a window’s view (a view whose parent is a window) inside an event procedure for that window. All Rules Language statements are allowed inside event processes. . then if a user clicks push button Z.1 Rules Language Reference Guide 7-7 . only Procedure Y is invoked. objects. the procedure with the narrowest scope is invoked—the procedure for the particular object.. and Procedure Y handles the click event for push button Z. If you define one event procedure for a type of object and another event procedure for a particular object of that type.Event Handling Procedure PROC windowInitialize FOR Initialize TYPE WINDOW OF GUI_KERNEL (p OBJECT TYPE InitializeEvent) .1. if Procedure X handles the click event for any push button.. ENDPROC You can use DCL statements to declare the same procedure for multiple events. or object types (see “Event Procedure Declaration”). . AppBuilder 2. For example.. Event Handling Procedure 7-8 Procedures . 1.1 Rules Language Reference Guide 8-1 .CHAPTER 8 CONTROL STATEMENTS AppBuilder 2.1.1 Rules Language Reference Guide The following is a list of control statements: • Comment Statement • ObjectSpeak Statement • File Access Statements • Post Event Statement • Compiler Pragmatic Statements • Assignment Statements • Condition Statements • Transfer Statements • Event Handler Statement in Java Control Statement Syntax comment_statement method_invocation_statement file_access_statement post_event_statement pragmatic_statement event_handler_statement assignment_statement condition_statement transfer_statement AppBuilder 2. Example 4 // This rule was last modified on January 26.14 to the variable PI The following are not valid comments: Example 3 *> This rule was last modified *> by adding line 5 <* on January 26.Comment Statement Comment Statement A comment describes the purpose of a Rules Language statement to other developers.14 to the variable PI <* MAP 3. including line breaks. Examples . 8-2 Control Statements . The remainder of the comment then causes a syntax error.Valid Comment Code An example of each type of valid comment follows: Example 1 *> assign the value 3. “//” denotes single line comments. 1995 <* MAP 3. Use *> <* instead for multi-line comments. 1995 The compiler does not recognize this comment because it is on more than one line. Comment Syntax *> any_text one_line_of_text <* // where: • any_text is any character sequence possible. See also “OVERLAY Statements in OpenCOBOL”.14 TO PI // Assign the value 3. Comments may continue across more than one line.14 TO PI Example 2 *> This rule was last modified on January 26. A “*>” denotes the beginning and “<*” denotes the end of a multiline comment. but you cannot nest comments. Any text within these delimiters is ignored when the rule is prepared. 1995 <* The compiler closes the comment after “line 5”. • one_line_of_text is any character sequence limited to one line (without any line breaks). followed by the method name. ObjectSpeak_reference method_name where ObjectSpeak_reference is: property_name method_name . they are enclosed within parentheses following the method name. and separated with commas. ( expression ) where object_name can be: • The system identifier (HPSID) of the object • The alias of the object (see “Object Data Items”) • An object (see “Object Data Types”) • An array (see “Array Object”) where: expression See “Expression Syntax”. For example: treeView. . Refer to the ObjectSpeak Reference Guide for more information.ObjectSpeak Statement ObjectSpeak Statement The ObjectSpeak extension to Rules Language allows you to invoke methods for objects supplied with AppBuilder. Invoking Methods for Objects The simplest method invocation is the object name followed by a period.ShowHelp If the method takes parameters. Note Do not include parentheses if the method has no parameters For example: CommonDialog. ObjectSpeak Syntax object_name .200) AppBuilder 2.1 Rules Language Reference Guide 8-3 .1.HitTest(100. the nesting can go to any level. the AppBuilder environment supports whatever ANSI version the underlying database supports. File Access Statements File access (or database access) statements include: • SQL ASIS Support • SQL ASIS Support in Java • START TRANSACTION • COMMIT TRANSACTION • ROLLBACK TRANSACTION For Java development. for example.File Access Statements Invoking Nested Methods Sometimes a method of a control is “buried” inside the control.Size. Thus. it might be a method of a property that is returned by a method of the control. doing so may cause problems when porting the code to another database. However. A rule can access a database directly by executing embedded SQL code specified as an argument to the SQL ASIS statement. simply use a period to separate each “nesting level. In theory.” For example: myWindow. you may also want to read: • Transaction Support in Java SQL ASIS Support The Rules Language supports access to various databases using SQL code embedded directly in a rule. When a method is nested. you can use nonstandard extensions supported by your database. SQL ASIS Syntax SQL ASIS sql_code ENDSQL START TRANSACTION COMMIT TRANSACTION ROLLBACK TRANSACTION 8-4 Control Statements .setWidth(newWidth) The setWidth method is a method of the Size property of the Window control named myWindow. Note Because it passes the embedded SQL directly to the underlying database’s SQL compiler. ) SQL code also cannot access multiple-occurring views. That loop needs to know when it has fetched all the rows the SELECT returns. But by declaring an SQL cursor into a selection. so you do not need to attach it to the rule yourself. And you can use the SQL return code values in your rule. The code between the keywords SQL ASIS and ENDSQL is copied “as is” into the generated code. you must use the implementation names of the files and fields used to create the table.1 Rules Language Reference Guide 8-5 . so you cannot simply SELECT data into an AppBuilder array. separating them by a period rather than by the keyword OF. The SQL code can use any non-multiple-occurring view or field in the rule’s data universe or any locallydeclared variable as a host variable. just as if they were locally declared fields. SQLCODE and the rest of the SQL Communication Area’s variables are accessible to any rule that uses the SQL ASIS command. A field name must be unambiguous. or WHENEVER statement because such statements do not affect the SQLCA. Do not check the SQLCODE field after a DCL CURSOR. INCLUDE. Do not use SELECT * in embedded SQL. For these statements. you can loop through the selection (each iteration of the loop can FETCH the row under the cursor INTO a locally declared view acting as a host variable). not to any database object. (This is similar to the syntax used in PL/I or C to identify the components of a structured variable. To make this possible. Note The SQLCA view is automatically appended to any rule that has DB2 usage.File Access Statements Usage You cannot nest SQL statements. enhancements to the table structure might make your host variables incompatible with the rows of the table. expressions beginning with a colon) correspond to variables in your rule.LAST_NAME SQL supports only one level of qualification. you qualify a field name by writing the view name first.) Thus. To access a structure that requires multiple levels of qualification. you can declare a local variable LIKE your target structure and reference the variable in the SQL code. But host variables (that is. That is. Refer to Developing Applications Guide for instructions on writing a user component. so they must be coded using the long name. Then you can MAP that view into one occurrence of a multiple-occurring view. In SQL code within a rule. a field that appears elsewhere in a rule as LAST_NAME OF CUSTOMER must appear in embedded SQL code as: :CUSTOMER. You must write and invoke a user component to access any file that does not support SQL statements. AppBuilder 2.1. (You can subsequently map data from your variable to the “real” data structure. you must redefine the view to “flatten” it. and then the field name. You can view the SQLCA in RuleView to examine the SQL return codes. There are three exceptions to this: • Host variables • Comments • SQL Communication Area (SQLCA) Most SQL ASIS statements reference database tables that are created by selecting Prepare from the popup menu displayed by right-clicking the File object in the Hierarchy or by selecting Prepare from the Build menu. All host variables are converted back to COBOL representation after SQL block is executed. however. Values with year 0 are not valid values in DB2. During code generations. Column2 From myTable Where Column3 = :myDate ENDSQL SQL ASIS open myCursor ENDSQL If we generate Classic COBOL code for that it will be the following (simplified for clarity): * SQL ASIS * CONVERSIONS BEFORE SQL * DATE TO CHAR IF (V--LOC-DATE-0001 OF V-SQLRULE-LOCAL-VARS < 367) THEN MOVE 367 TO V--LOC-DATE-0001 OF V-SQLRULE-LOCAL-VARS. OpenCOBOL and C generation. Classic COBOL DATE. DEC fields do not have the same representation as corresponding DB2 column types. then converted to DB2 representation. To solve this problem. To solve this problem each host variable of DATE type containing the value less than 367 (year 0 in AppBuilder) is replaced with value 367 or 0001/01/01. TIMESTAMP. The converted value is stored in the temporary variable. only limited analysis of the SQL code within SQL ASIS ENDSQL blocks is done. 8-6 Control Statements . in AppBuilder they are valid values. all host variables of these types are converted to DB2 representation. and this temporary variable is used as a host variable in the generated COBOL code. The rest of the code is generated in the COBOL program AS IS. This conversion problem is solved using EDEFINE fields. This verification is done in ClassicCOBOL and OpenCOBOL. In OpenCobol no conversion is necessary because data types used in COBOL programs are the same as DB2 with the exception of TIME fields. Conversion is done before and after each SQL ASIS block. Examples using SQL ASIS Example 1 using SQL ASIS with host variables DCL myDate date. After each SQL block all data values that are less or equal 367 are replaced with value 0. There is no analysis of which variable is input variable and which one is output. ENDDCL SQL ASIS Declare myCursor cursor for Select Column1. DB2 does not allow DATE value 0000/00/00 which is initial value for DATE fields in Appbuilder. OpenCOBOL has an option to use string comparison instead of converting the date to a number and comparing with value 367. Mainly the host variables used in the code are analyzed.File Access Statements Using SQL host variables in the rules for Classic COBOL. TIME. without changes. All host variables used in the block are converted to DB2 types before SQL block. However if we change the original rule code to be: DCL myDate date. Column2 From myTable Where Column3 = :V--SMT-SQL-1 END-EXEC * * V-- CONVERSIONS AFTER SQL CHAR TO DATE CALL 'CGCH2DT' USING DFHEIBLK DFHCOMMAREA V--LOC-DATE-0001 OF V-SQLRULE-LOCAL-VARS. ENDDCL SQL ASIS Declare myCursor cursor for Select Column1. EXEC SQL open myCursor END-EXEC This code will work because the value of V--SMT-SQL-1 which is implicitly used in OPEN statement has not change between EXEC SQL statements. V--LOCDATE-0001 OF V-SQLRULE-LOCAL-VARS EXEC SQL AppBuilder 2. Column2 From myTable Where Column3 = :myDate ENDSQL set myDate := date () SQL ASIS open myCursor ENDSQL Then COBOL code will be: * SQL ASIS * CONVERSIONS BEFORE SQL * DATE TO CHAR IF (V--LOC-DATE-0001 OF V-SQLRULE-LOCAL-VARS < 367) THEN MOVE 367 TO V--LOC-DATE-0001 OF V-SQLRULE-LOCAL-VARS. LOC-DATE-0001 OF V-SQLRULE-LOCAL-VARS EXEC SQL Declare myCursor cursor for Select Column1. V--SMT-SQL-1 IF (V--LOC-DATE-0001 OF V-SQLRULE-LOCAL-VARS < 368) THEN MOVE 0 TO V--LOC-DATE-0001 OF V-SQLRULE-LOCAL-VARS.1 Rules Language Reference Guide 8-7 .File Access Statements CALL 'CGDT2CH' USING DFHEIBLK DFHCOMMAREA V--SMT-SQL-1. CALL 'CGDT2CH' USING DFHEIBLK DFHCOMMAREA V--SMT-SQL-1.1. This happened because OPEN statement has no host variables and there is no conversion. all host variables used in any SQL ASIS block in the rule are converted and verified before and after each SQL block. When it is used. The SELECT statement lists the DB2 column names equivalent to the fields of interest. To solve this problem the code generation option -H was introduced. but V--SMT-SQL-1 has not been updated. This may be unnecessary overhead but it is the only way to solve the problem without implementing SQL parser. MOVE TMP0 OF V-SQLRULE-TEMP-VARS TO V--LOC-DATE-0001 OF V-SQLRULE-LOCAL-VARS. V--SMT-SQL-1 IF (V--LOC-DATE-0001 OF V-SQLRULE-LOCAL-VARS < 368) THEN MOVE 0 TO V--LOC-DATE-0001 OF V-SQLRULE-LOCAL-VARS. Column2 From myTable Where Column3 = :V--SMT-SQL-1 END-EXEC * * CONVERSIONS AFTER SQL CHAR TO DATE CALL 'CGCH2DT' USING DFHEIBLK DFHCOMMAREA V--LOC-DATE-0001 OF V-SQLRULE-LOCAL-VARS. The name to look for is in the field SEARCH_NAME of the rule’s input view.SEARCH_NAME ENDSQL DO FROM 1 TO 25 INDEX I SQL ASIS FETCH CURS_1 INTO :CUSTOMER_TEMP ENDSQL WHILE SQLCODE = 0 8-8 Control Statements .File Access Statements Declare myCursor cursor for Select Column1. DFHCOMMAREA. Example 2 . EXEC SQL open myCursor END-EXEC This code will produce the wrong result. CUSTOMER_TEMP LIKE CUSTOMER. FIRST_NAME. DCL I INTEGER. ENDDCL SQL ASIS DECLARE CURS_1 CURSOR FOR SELECT LAST_NAME. because V--LOC-DATE-0001 has changed. ID_NUM FROM CUSTOMER_TABLE WHERE LAST_NAME = :RULE3I. TMP0 OF V-SQLRULE-TEMP-VARS. CALL 'CGDATE' USING DFHEIBLK.SQL Sample The following rule reads all the customers with a given last name from the CUSTOMER_TABLE database into a multiple-occurring view called CUSTOMER_LIST. changes to local databases are not committed until the AppBuilder process terminates. Unless a transaction is committed explicitly using COMMIT TRANSACTION. AppBuilder 2. implicit rollbacks affect only remote databases on server machines.File Access Statements MAP CUSTOMER_TEMP TO CUSTOMER_LIST OF RULE3O (I) ENDDO START TRANSACTION Use START TRANSACTION to start a database transaction explicitly. ROLLBACK TRANSACTION Use ROLLBACK TRANSACTION to roll back changes to local and remote databases since the previous START TRANSACTION statement. a remote database commit could succeed while a local one fails. COMMIT TRANSACTION Use COMMIT TRANSACTION to commit changes to local and remote databases since the previous START TRANSACTION statement. (AppBuilder translates it for the database being used. By contrast. For example.(AppBuilder translates it for the database being used.1 Rules Language Reference Guide 8-9 . Note The commits performed by a COMMIT TRANSACTION are not coordinated among multiple locations. changes to remote databases are committed or rolled back depending upon settings in the DNA. you can commit or roll back changes to both local and remote databases subsequent to the START TRANSACTION using COMMIT TRANSACTION or ROLLBACK TRANSACTION.) • It works on local databases as well as remote databases. the advantage of using COMMIT TRANSACTION is: • It is database independent.1.) • It works on local databases as well as remote databases. A transaction is started implicitly when you use a remote rule (one running on a server machine) that accesses a database.INI file. implicit commits affect only remote databases on server machines. Although you can also roll back a database using SQL ASIS ROLLBACK. If a transaction is started implicitly. Although you can also commit a database using SQL ASIS COMMIT. If a transaction is started explicitly. By contrast. the advantage of using ROLLBACK TRANSACTION is: • It is database independent. Therefore it is useless at the end of the rule code. or to a different rule in the same application. the PRAGMA statement should not be the last statement in the Rule because it affects subsequent statements only. These PRAGMA clauses include: • PRAGMA KEYWORD • PRAGMA CLASSIMPORT for Java • PRAGMA AUTOHANDLERS for Java • PRAGMA ALIAS PROPERTY for Java • PRAGMA SQLCURSOR for Java • PRAGMA CENTURY for OpenCOBOL PRAGMA Syntax PRAGMA KEYWORD CLASSIMPORT AUTOHANDLERS ALIAS PROPERTY COMMONHANDLER CENTURY Note See the individual topics for an explanation of the syntax for each statement. See “CONVERSE for Global Eventing” for information on posting and receiving global-event messages. 8-10 Control Statements . The compiler PRAGMA statement can be used between any language constructions but cannot be used inside of a construction. The text of the message is contained in the view attached to the event.Post Event Statement Post Event Statement Use a POST EVENT statement to post a message to another application. In addition. POST EVENT Syntax POST EVENT event_name For example: POST EVENT CUTOFF_REACHED START_NEW Compiler Pragmatic Statements Compiler PRAGMA statements are special commands that control certain features of the compiler. The PRAGMA KEYWORD clause is case-insensitive.true) AppBuilder 2. Separate individual keywords using commas (spaces are ignored) and place the entire list in parentheses.1. The Rules Language keywords that can be switched on or off with the PRAGMA clause are listed in the following sections: • Keywords for Java that can be disabled with PRAGMA KEYWORD • Keywords for C that can be disabled with PRAGMA KEYWORD • Keywords for ClassicCOBOL that can be disabled with PRAGMA KEYWORD • Keywords for OpenCOBOL that can be disabled with PRAGMA KEYWORD.Using PRAGMA to Switch Keywords On and Off Keywords true and false are switched on and off. it must be the last PRAGMA statement in a rule. Not all keywords can be turned on or off. Example . so keywords can be lower or uppercase Note If the PRAGMA KEYWORD OFF (PRAGMA) clause is used.Compiler Pragmatic Statements PRAGMA KEYWORD The PRAGMA KEYWORD is used to switch selected Rules Language keywords on or off. PRAGMA KEYWORD Syntax PRAGMA KEYWORD ON OFF ( keywords_list ) where keywords_list is the parameters list of keywords to switch on or off. The default value is ON for all of the keywords listed.false) PRAGMA KEYWORD off (false.1 Rules Language Reference Guide 8-11 . PRAGMA KEYWORD on (true) PRAGMA KEYWORD off (true) PRAGMA KEYWORD on (true. Compiler Pragmatic Statements 8-12 Control Statements . 1 Rules Language Reference Guide 9-1 . Related topics include: • Data Type Mapping Errors • Mapping Data AppBuilder 2.1 Rules Language Reference Guide Assignment statements allow you to assign a new value to a variable data item.CHAPTER 9 ASSIGNMENT STATEMENTS AppBuilder 2.1. These statements include: • Assignment Statements • CLEAR Statement • OVERLAY Statement Besides using the three statements listed above. You can map any valid expression to a field variable. provided that the expression and the field are of compatible data types.1. You can also assign variables of the Object data type. you can also assign new data to a view by using the special redefine capability. These alternatives are discussed in: • Redefining Views • Assigning Object Data Type Variables in Java Assignment Statement Syntax assign_statement clear_statement overlay_statement Assignment Statements A MAP statement copies the value of the source item to the target item. view aggregate rule_name component_name TO view . SET variable_data_item := +:= -:= view aggregate rule_name component_name expression view := ( view aggregate expression ) .Assignment Statements MAP and SET Syntax MAP expression TO variable_data_item . where: expression See “Numeric Expressions”. Aggregate Syntax . 9-2 Assignment Statements . ( view aggregate expression ) . { expression aggregate view_name rule_name component_name } ( view aggregate expression ) . Text TO ButtonText The SET statement is an analog of the MAP statement with certain limitations.Background MAP 'OK' TO OK_Button. the value of the source expression is calculated separately before each mapping. VIEW_A(2) to VIEW_B(2). Thus. Conversely. and the target item is multiple data items (separated by a comma). This allows for a slightly different value to be mapped to each target data item depending upon the type (precision) of the target item.Foreground to OK_Button. AppBuilder 2. Usage Note If the source item is a numeric expression. If the object PUSHBUTTON contains methods: You use the following syntax in Java mode: MAP OK_Button. MAP VIEW_A TO VIEW_B maps VIEW_A(1) to VIEW_B(1). that output view is mapped to the destination after the rule call. it maps data from a field in a subview of the first view to a field in the subview of the second view if the: • Subviews are directly attached to the views being mapped • Names of the subviews are identical You can also map to or from a multiple-occurring view. If only one of the views is multiple-occurring. 32500) to V MAP res of v TO f3 The source of the MAP can be any method call or any variable from the object. This maps the data in any field under the first view to a field with the same name under the second view. until one of the two views runs out of occurrences. this maps the same numbered view from the first view to the other as for a regular view. which can be seen on the syntax diagram. and so on.1 Rules Language Reference Guide 9-3 . If the object is a window object. the data in the non-occurring view maps to or from the first occurring view. Thus.1. you can only map another view to it. If the variable is a view.Assignment Statements variable_data_item view See “Variable Data Item”. then it is possible to use its system identifier (HPSID) without declaring this object in the rule’s DCL section. if VIEW_A is not multipleoccurring but VIEW_B is. use: MAP OK_Button. the statement maps VIEW_A to VIEW_B(1). Assume there is a window attached to the rule and this window contains the object PUSHBUTTON with the system identifier (HPS ID) of ‘OK_BUTTON’. If both views are multiple-occurring. In addition. In this case. the statement maps the first occurrence of VIEW_A to VIEW_B.Text and in C mode. the rule name should be used without USE. For example: MAP integer_sum (1. if VIEW_A is multiple-occurring and VIEW_B is not. in the statement above. See “View”.ForeColor to color MAP OK_Button. The source of a MAP statement can be a RULE call. any INTEGER field containing a value greater than 32. first_name. “first name”. if the source field equals +32. birthday date. The right hand side expression will be added or subtracted from the variable_data_item. These messages flag statements that might. where the INTEGER row meets the SMALLINT column. 9-4 Assignment Statements . suppose you have the following declaration: DCL last_name. DBCS and MIXED mappings are only applicable to releases that support DBCS. age_view. my_age like age_view. age_view view contains birthday. “first name”. “W” indicates that if you map an INTEGER field to a SMALLINT field.‘%m/%d/%y’). See Release Specific Considerations for more information. age integer. lead to errors or unpredictable results at runtime. To do this. In addition. For example. a warning message is added to your preparation results file. For example. and those which are legal. when the rule is executed. first_name varchar (20). For example.34}} to person_view Data Type Mapping Errors Any attempt to map a field or constant to a field of an incompatible data type produces an error when you try to prepare the rule. If you have a rule that maps a INTEGER field to a SMALLINT field. {DATE(‘12/29/61’. a warning message is added in your preparation results file.768. you get a warning message for any MAP statement whose source field data type is potentially incompatible with the data type of its destination field. ENDDCL The following example uses an aggregate to map three values to person_view: MAP {“last name”. For example: SET I:=1 SET I+:=1 *>sets I to 2<* SET I-:=1 *>sets I to 1<* Using Aggregates The source of MAP can be aggregate. Using an aggregate allows you to map several values with a single map statement.767 or less than -32. However. it is perfectly legal to map an INTEGER field to a SMALLINT field because the two data types are compatible. my_age } to person_view The following example uses nested aggregates to map to person_view: MAP {“last name”. the target field becomes -1.Assignment Statements Increment and Decrement SET Statements A SET statement can be used to increment or decrement a numeric variable by any value without writing addition or subtraction. person_view view contains last_name. under certain conditions. Table 9-1 shows combinations of source and destination fields that result in errors or warnings.767 maps incorrectly to the SMALLINT field. For example. age. write +:= or -:= . 1 Rules Language Reference Guide MIXED 9-5 CHAR DBCS DATE TEXT TIME . You can assign a DBCS literal to CHAR field. Mapping Data You map data as described in the following sections: • Mapping To or From a PIC Field • Mapping To a DEC Field • Mapping Between Fields of Different Lengths • Mapping To or From a VARCHAR Field • Mapping a View to a View Example .Assignment Statements Table 9-1 Source and Destination Field Mapping Results PIC (unsigned) PIC (signed) TIMESTAMP SMALLINT VARCHAR DECIMAL INTEGER IMAGE SMALLINT INTEGER DECIMAL CHAR VARCHAR PIC (signed) PIC (unsigned) DATE TIME TIMESTAMP TEXT IMAGE DBCS MIXED L=Legal L W W E E L L E E E E E E E L L W E E L L E E E E E E E L L L E E L L E E E E E E E E E E L L E L E E E L L Ea L E E E L L E L E E E L L Ea L L L L E E L L E E E E E E E W W W E E W L E E E E E E E E E E E E E E L E E E E E E E E E E E E E E L E E E E E E E E E E E E E E L E E E E E E E L L E L E E E L E E L E E E L L E L E E E E L E L E E E E E E E E E E E E L E E E E L L E L E E E L L L L W=Warning E=Error a.1. but not a variable of type DBCS.Mapping Data to a Field The following rules code illustrates the most common form of mapping data to a field: MAP 10 TO NUMBER_OF_PEOPLE *> Copies the value of the numeric literal 10 into the field <* MAP '223 West 21st Street' TO ADDRESS OF CUSTOMER_DETAIL *> Copies the value of the character literal <* *> '223 West 21st Street' into the field ADDRESS <* MAP ADDRESS OF CUSTOMER_DETAIL TO ADDRESS OF SHOW_CUSTOMER_DETAIL *> Copies the value of the first ADDRESS field into the second <* *> ADDRESS field <* AppBuilder 2. The remaining positions are filled with blanks. or • does not have enough places to the right of the decimal to hold its fractional part Similarly. Mapping Between Fields of Different Lengths Although the data types are compatible. the destination field is set 9-6 Assignment Statements . For example. If a source string is longer than the maximum length of a target VARCHAR field. the characters that fit into the field are mapped and the length is set to the maximum length of the field. the length associated with that VARCHAR field is set to the length of the string. the destination field stores only as many characters as can fit from the start of the string. and the remaining character spaces in the VARCHAR field are set to blanks. For example. In this event. You cannot map a PIC field containing either a sign code (‘S’) or a decimal placeholder (‘V’) to a CHAR or VARCHAR field. Conversely. Mapping To a DEC Field Mapping more digits than allowed to a DEC field results in a run-time error. When you map a valid PIC field to a CHAR or VARCHAR field.DISCOUNT) * TAX_RATE TO SALES_TAX *> Copies the value to which the expression resolves <* *> into the field SALES_TAX <* MAP JAN IN MONTHSET TO WHICH_MONTH *> Copies the value of the symbol Jan [not the symbol name] into <* *> into the field WHICH_MONTH <* Mapping To or From a PIC Field You can map an unsigned PIC field to either a character or a numeric field. Any string longer than the character field to which it is mapped is truncated. then the destination field is set to 'Hello ' and its length is set to 5. you get an error if you attempt to map a numeric constant to a DECIMAL or PIC field that either: • does not have enough places to the left of the decimal to hold its integer part. INTEGER. if the string 'Hello' is mapped to a VARCHAR field with a maximum length of 3.Assignment Statements MAP (PRICE . Mapping To or From a VARCHAR Field Mapping to a VARCHAR field is a complicated procedure because a VARCHAR field contains a length property. a CHAR or VARCHAR destination field might be too short to contain a source field that is mapped to it. but you cannot map a character value to any PIC field. a string is left justified if the length of its destination field is greater than the length of the source field. You receive a warning in your preparation results if you MAP a field of format SMALLINT. assume a VARCHAR field’s length is 5 and the field contains the string 'Hello'. the value of the character field is set to a string representing the number in the PIC field. When you map a string into a VARCHAR field. causing RuleView to display asterisks in the field. or DECIMAL to a PIC field whose picture does not begin with an ‘S’ to allow for a negative sign. If it is mapped to a VARCHAR field with a maximum length of 10. or a symbol of type CHAR). The length of B is determined from the length of A in a MAP A TO B statement as follows: If length of A <= maximum length of B. When you map a CHAR field to a VARCHAR field. Example . the length of VARCH_VAR_2 <* MAP VARCH_VAR_2 TO VARCH_VAR_1 *> Copies the value '** MY LENGTH IS' into varch_var_1 and <* *> sets length of varch_var_1 to 15. the length of char_var_1 CHAR (10). even if the string in the CHAR field is shorter. CHAR (20). VARCHAR (15). the length of 'ABC ' MAP CHAR_VAR_1 TO VARCH_VAR_1 *> Copies the value 'ABC ' into varch_var_1 and *> sets length of varch_var_1 to 10.Mapping Data to a VARCHAR Field The following Rules code example illustrates how mapping data to a VARCHAR field affects its contents and length: DCL CHAR_VAR_1 CHAR_VAR_2 VARCH_VAR_1 VARCH_VAR_2 ENDDCL MAP 'ABC ' TO CHAR_VAR_1 MAP '** MY LENGTH IS 20 *' TO CHAR_VAR_2 MAP 'ABC ' TO VARCH_VAR_1 *> Copies the value 'ABC ' into varch_var_1 and *> sets the length of varch_var_1 to 4.1. If a source string is shorter than a target VARCHAR field. assume B is a variable of type VARCHAR and A is a character value (a variable.Assignment Statements to 'Hel' and its length is set to 3.1 Rules Language Reference Guide 9-7 . the length of VARCH_VAR_1 <* MAP CHAR_VAR_2 TO VARCH_VAR_2 *> Copies the value '** MY LENGTH IS 20 *' into varch_var_2 and<* *> sets length of varch_var_2 to 20. Thus. any positions in the target not containing new data are set to blanks and the length of the target is set to the length of the source. then: Length of B = length of A The contents of B equals the contents of A padded with spaces to the right. In summary. the length of the VARCHAR field is set to the length of the CHAR field (10) and not to the length of the string (5). if the string 'Hello' is stored in a CHAR (10) field and then mapped to a VARCHAR (20) field. a literal of type VARCHAR or type CHAR. the length associated with the VARCHAR field is set to the defined length of the CHAR field. then: Length of B = maximum length of B The contents of B equals the first “max length of B” characters of A. VARCHAR (20). <* <* <* <* MAP CHAR_VAR_2 TO VARCH_VAR_1 *> Copies the value '** MY LENGTH IS' into varch_var_1 and <* *> sets length of varch_var_1 to 15. the length of VARCH_VAR_1 <* AppBuilder 2. If length of A > maximum length of B. mapping is the only operation you can perform on a TEXT or IMAGE field. It only checks if the shift control characters are balanced for MIXED fields. the length of VARCH_VAR_1 <* Mapping To or From a TEXT or IMAGE Field Fields of these types are stored as CHAR (256) fields. TEXT. it is validated. Similarly. You cannot map a value from a TEXT field to an IMAGE field. you can map a value between two IMAGE fields or between an IMAGE field and a character field. The MIXED and DBCS data types are discussed on DBCS and MIXED Data Types. You can perform the following operations on these variables: MAP 'd:\bitmaps\our_logo' TO LOGO_FILE *> Copies the indicated string to logo_file <* MAP LOGO_FILE TO CHAR_FIELD *> Copies the value in logo_file to char_field <* MAP INFO_FILE_1 TO INFO_FILE_2 *> Copies the value in info_file_1 to info_file_2 <* Mapping To or From a DBCS or MIXED Field You can map a MIXED field to another MIXED field or a DBCS field to another DBCS field. you can map a value between two TEXT fields or between a TEXT field and a character field. so the conditions that apply to CHAR fields also apply to TEXT and IMAGE fields. If validation fails. Standard warnings about possible truncation still apply in any situation. In Java and ClassicCOBOL.Assignment Statements MAP VARCH_VAR_1 TO VARCH_VAR_2 *> Copies the value '** MY LENGTH IS ' into varch_var_2 and <* *> sets length of varch_var_2 to 15. assignment does not perform such validation. to map between data types where assignment is not directly allowed you must use the appropriate conversion function. or vice versa. In Java. Whenever a value of any acceptable type is being assigned to a MIXED or DBCS variable. an exception is raised at runtime. either CHAR. the validation codepage is specified by the DBCS_VALIDATION_CODEPAGE parameter in the [VALIDATION] section of the appbuilder. CHAR (256). MIXED. For example. This ini setting can be changed without recompilation. In OpenCOBOL. That is. 9-8 Assignment Statements . In addition. and the conversion functions are discussed in “Double-Byte Character Set Functions”. See corresponding rows and columns in Table 9-1. TEXT. validation determines whether or not the source actually is a valid MIXED or DBCS value according to the specified codepage. or DBCS. assume that a rule contains the following statements: DCL LOGO_FILE INFO_FILE_1 INFO_FILE_2 CHAR_FIELD ENDDCL IMAGE. However.ini file. you cannot use the following statements: MAP MAP MAP MAP MAP MAP MAP MAP MAP MAP MAP MAP D1 TO C1 D1 TO M1 M1 TO C1 M1 TO D1 C1 TO M1 C1 TO D1 SYM_D_1 TO SYM_D_1 TO SYM_M_1 TO SYM_M_1 TO SYM_C_1 TO SYM_C_1 TO CHAR (10). validation verifies that the shift control characters are balanced and both bytes of each DBCS character are either 0x40 (DBCS space) or in the 0x41-0xFE (inclusive) range. MIXED (10). C1 M1 C1 D1 M1 D1 Instead. Consider an example that applies to C mode assuming that a rule contains the following statements: DCL C1 M1 D1 ENDDCL Assume also that the repository contains a: • Set SET_C of type CHAR (10) with symbols SYM_C_1 • Set SET_M of type MIXED (10) with symbols SYM_M_1 • Set SET_D of type DBCS (10) with symbols SYM_D_1 In that case. the function returns spaces and in the case of DBCS data types an error message is issued at runtime.Assignment Statements In ClassicCOBOL.1 Rules Language Reference Guide 9-9 . If validation fails. you must use these statements: MAP MAP MAP MAP MAP MAP MAP MAP MAP MAP CHAR(D1) TO C1 MIXED(D1) TO M1 CHAR(M1) TO C1 MIXED(C1) TO M1 CHAR(SYM_D_1) TO C1 MIXED(SYM_D_1) TO M1 CHAR(SYM_M_1) TO C1 DBCS(SYM_M_1) TO D1 MIXED(SYM_C_1) TO M1 DBCS(SYM_C_1) TO D1 The analogy holds true for character literals as well: MAP CHAR ('ABCDE') TO C1 MAP MIXED ('ABCDE') TO M1 MAP DBCS ('#@') TO D1 These statements could also be written as: MAP 'ABCDE’ TO C1 MAP 'ABCDE' TO M1 AppBuilder 2.1. DBCS (10). APPLICANT and EMPLOYEE. 9-10 Assignment Statements . Figure 9-1 Two views for MAP example The statement MAP APPLICANT TO EMPLOYEE copies the data in the fields: CITY OF EMP_ADDR OF APPLICANT STATE OF EMP_ADDR OF APPLICANT NAME OF DOCTOR OF APPLICANT to the corresponding fields: CITY OF EMP_ADDR OF EMPLOYEE STATE OF EMP_ADDR OF EMPLOYEE NAME OF DOCTOR OF EMPLOYEE The value in COMPANY of LAST_JOB of APPLICANT is not copied anywhere.Assignment Statements MAP '#@' TO D1 Mapping a View to a View AppBuilder uses two methods to map one view to another. however. a field in the source view is copied to a field in the target view if both fields have the same name and occupy the same relative position (only have same-named parents) in both views. assume you have two views. If all the fields in the source and target views have different names. it is helpful to understand how it chooses the methods and how they work. Nothing is copied into OFFICE of DEPARTMENT of EMPLOYEE because APPLICANT does not directly include any view named DEPARTMENT. because EMPLOYEE does not directly include any view named LAST_JOB. the second method is used. For example. Map Same-Named Fields In this method. The code generation utility selects the method to use. as shown in Figure 9-1. • Map Same-Named Fields • Map Same-Typed Fields The first one is chosen by the code generation facility when there is at least one field in the source view that has the same name as the name of a field in the target view. Two fields have the same relative data types if: • Both are either character or large object • Both are numeric • Both are date • Both are time • Both are timestamp • Both are boolean For example. If CLEAR is applied to a view.) fields in their respective views.1. then AppBuilder attempts a second method of mapping fields. In this method.1 Rules Language Reference Guide 9-11 . or third. CLEAR Syntax CLEAR variable_data_item view where: variable_data_item view See “Variable Data Item”.CLEAR Statement NAME of APP_NAME of APPLICANT is not copied to NAME of EMP_NAME of EMPLOYEE because the source and destination views do not directly include the NAME fields and the views that include them are named differently. See “View”. the result is the same as if CLEAR were applied to every field and subview of that view. If it fails.. CLEAR Statement A CLEAR statement sets the value of the specified variable to its initial value.. a SMALLINT field is converted to an INTEGER and copied to an INTEGER field if both fields are the first (or second. a compile-time error is issued. AppBuilder 2. a field in the source view is converted to the proper data type and copied to a field in the target view. This type of mapping is performed only when all fields from the source view can be converted to data types of fields in the target view. Refer to “Initialization” for information on initial values. assuming both fields have the same relative data type and occupy the same relative position in both views. Map Same-Typed Fields If no field can be copied to any other field according to the same-named method. This is accounted for when you use a VARCHAR variable in a MAP statement. Refer also to Using OVERLAY Statements with Variable Data. Using OVERLAY Statements with Character Data One of the main purposes of OVERLAY is to bypass the MAP safety mechanisms. For example. because DEC data items are packed on the host. so this length information does not cause any problems. refer to: • OVERLAY Statements in C • OVERLAY Statements in Java • OVERLAY Statements in ClassicCOBOL • OVERLAY Statements in OpenCOBOL Using Overlay Statement with VARCHAR Data Items requires additional consideration and caution. you must compensate for this fact when you overlay with or over a VARCHAR variable. 9-12 Assignment Statements . an OVERLAY action is a blind. refer to this section for details. The system determines the starting memory location of the first variable. determines the starting memory location for the second variable. However. See “View”. be aware of platform-dependent storage differences. Review the descriptions in the following sections before using OVERLAY statements or porting an application with OVERLAY statements to a different platform. and moves the block of data to that location. Thus. copies that data into one block. they have more bytes on the workstation than on a host. However. Using Overlay VARCHAR data is platform-dependent.OVERLAY Statement OVERLAY Statement An OVERLAY statement copies the value of the first item into the second item where variable_data_item is of type CHAR or VARCHAR. Depending on the language of application development. OVERLAY Syntax OVERLAY view view variable_data_item TO TO variable_data_item view where: variable_data_item view See “Variable Data Item”. memory copy. Internally. Using Overlay Statement with VARCHAR Data Items Use extreme care when using OVERLAY with VARCHAR data items. byte-by-byte. a VARCHAR length information is stored in its first two bytes. if they have the same memory offset in the source and the destination. V_view_1 V_view_2 VIEW CONTAINS V_int.Using OVERLAY with SMALLINT. V_small_1. because DEC data items are packed on the host. However. ENDDCL MAP timestamp TO V_stamp OF V_view_1 It is safe to assume that the statement OVERLAY V_view_1 TO V_view_2 results in the correct value in V_stamp OF V_view_2 and that this value is the same as the value of V_stamp OF V_view_1. For example. Example . TIME. AND CHAR If a rule contains the following declarations and initialization statements: DCL V_int INTEGER.1 Rules Language Reference Guide 9-13 . because both fields have the same memory offset 4 in the source and in the destination. and OVERLAY FIELD TO VIEW where FIELD is of the type CHAR or VARCHAR. Refer also to Using OVERLAY Statements with Character Data. V_stamp. (See “Using Overlay Statement with VARCHAR Data Items” for more details. VIEW CONTAINS V_small_1. OVERLAY VIEW TO FIELD. DEC and PIC data types and when using data items of different lengths. V_small_2.) If an OVERLAY statement has VARCHAR as the destination.1. be aware of platform-dependent storage differences. Note Valid combinations for OVERLAY statements are: OVERLAY VIEW TO VIEW. V_stamp TIMESTAMP. the data items of these types have the same amount of memory allocated and it is safe to overlay one data item with another of the same type. Use the OVERLAY statement with caution with VARCHAR. V_small_2 SMALLINT. it is safe to use an OVERLAY statement with data items of the following types: • SMALLINT • INTEGER • DATE • TIME • TIMESTAMP • CHAR Regardless of the platform.OVERLAY Statement In some cases. DATE. AppBuilder 2. INTEGER. Using OVERLAY Statements with Variable Data One of the main purposes of OVERLAY is to bypass the MAP safety mechanisms. VARCHAR Data Types Data items of type VARCHAR can be used in OVERLAY statements only if the user takes into account that VARCHAR data item lengths are stored in the first two bytes. V_stamp. the semantics of such a statement is not the same as in the general case. they have more bytes on the workstation than on a host. TIMESTAMP. These ASCII characters would have binary values of 5 and 0. the representation and contents are different. The first two bytes of the destination field contain value n. V_view_2 VIEW CONTAINS V_varchar_5_2. starting from the third byte. where ## stands for two ASCII characters representing the ASCII value of the length of V_varchar_5_1 field. In this case. However. V_varchar_9 VARCHAR(9). The statement OVERLAY V_view_1 TO V_varchar_9 results in V_varchar_9 having a length of 7 and containing ‘##Hello’. Example . overlays between the two types result in invalid representation and corrupt data. This happens because here the destination is seen as a view. rather than a VARCHAR. the ASCII characters would have binary values of 5 and 0.20) and DEC(27. V_view_3 VIEW CONTAINS V_varchar_9. where ## stands for two ASCII characters representing the ASCII value of the number of bytes copied from the source view V_view_1. putting the binary value 0 in a VARCHAR can cause some unfortunate side effects. Warning Although tolerated by the Rules Language.25) have the same representation because they have the same amount of memory allocated for their storage. DEC and PIC Data Types Use extreme caution when using OVERLAY statements with PIC and DEC data items. and no offsetting is done to deal with the first two bytes of the VARCHAR. For example. AppBuilder is not designed to work with corrupted PIC and DEC data items. Only DEC or PIC data items that have the same length and scale should be used in OVERLAY statements.OVERLAY Statement If the destination is a VARCHAR field then an OVERLAY statement copies n bytes from source (where n is the minimum from two values: source length and maximum length of VARCHAR field) into the destination field. 9-14 Assignment Statements . V_varchar_5_2 VARCHAR(5). which is 5 in this instance. although it may seem that DEC(27. the statements OVERLAY V_view_1 TO V_view_2 OVERLAY V_view_1 TO V_view_3 result in V_varchar_5_2 and V_varchar_9 containing the same value ‘Hello’. No assumption can be made about the amount of memory allocated for the storage of DEC and PIC data items. V_view_1 VIEW CONTAINS V_varchar_5_1. the apparent truncation of data on display can effect system routines that treat the 0 as a string terminator. The number of bytes cannot exceed the length of the destination.Using OVERLAY with VARCHAR Data Types If a rule contains the declarations and initialization statements: DCL V_varchar_5_1 VARCHAR(5). ENDDCL MAP ‘Hello’ TO V_varchar_5_1 then the statement OVERLAY V_view_1 TO V_varchar_5_2 results in V_varchar_5_2 having a length of 5 and containing ‘##Hel’. For example. V_char_2. V_smallint. This behavior should be taken into consideration when overlaying multiple-occurring views. I smallint. and performs memory copy of all occurrences of the source view to the destination address. If a rule contains the following declarations and initialization statements: DCL V_char_3 V_char_2 V_char_5 V_smallint V_view_1 V_view_2 V_view_11 V_view_22 CHAR(3). the rest of the target remains unchanged.OVERLAY Statement Data Items of Different Length Use extreme caution when overlaying data items that have different lengths. TO V_view_11 AppBuilder 2.1 Rules Language Reference Guide 9-15 . Example . If the source is longer than the destination. however. If a data item used as destination in an OVERLAY statement is longer than the source data item. However. • The tenth occurrence V_view_1 in V_view_11 contains the value ‘##’ in the field V_char_3 (note that the third character is a blank symbol and ## stands for two ASCII characters that represent binary value 32) and character value contains blanks in the field V_char_2. then only the number of bytes equal to the length of the destinations is copied. On some platforms. The OVERLAY statement for multiple-occurring views does not use the same algorithms as the MAP statement. VIEW CONTAINS V_char_5. OVERLAY performs a byte-by-byte copy of the source then fills the rest of the target with blanks.Sample OVERLAY Statement Failure The following example describes a situation where the OVERLAY statement fails. VIEW CONTAINS V_char_3. ENDDCL MAP 32 TO V_smallint OF V_view_22 DO TO 9 INDEX I MAP ‘Hello’ TO V_char_5 OF V_view_22 ENDDO Then the statement MAP V_view_22 TO V_view_11 (I) results in V_smallint OF V_view_11 containing the value 32 and the rest of the fields in V_view_11 remain unchanged. the statement OVERLAY V_view_22 results in: • The first nine occurrences of V_view_1 in V_view_11 contain the value ‘Hel’ in the field V_char_3 and the value ‘lo’ in the field V_char_2. CHAR(5). VIEW CONTAINS V_view_1(10). On other platforms. SMALLINT. V_smallint. CHAR(2).1. VIEW CONTAINS V_view_2(9). the semantics of the OVERLAY statement can vary on different platforms. those first ten characters in storage are used to fill fields B1. The data in the fields of VIEW_A is copied and the copied data replaces the stored representation of VIEW_B. A2. which is an integer representation of the two bytes containing blanks. the last two characters of A1 and the first character of A2 are used for B2. For instance. respectively. Using OVERLAY Statements in a VARCHAR Data Item Suppose a rule contains the following declaration: DCL CHAR_VAR_1 CHAR (5). If VIEW_A in Figure 9-2 was a character literal or a character field that contained the string ‘aaaaabbbbcdddeeeee’. B2.OVERLAY Statement • V_smallint contains value 8224 on the PC. Where the structures of the two views differ. Using OVERLAY Statements in Multiple-Occurring Views The OVERLAY statement deals with multiple-occurring views in exactly the same way it does for nonmultiple-occurring data items. and B2 ends up holding ‘aab’. and ‘c’. when VIEW_A is overlaid on VIEW_B. a block copy of memory occurs. Because only the first three characters fit into B1. In both cases. Figure 9-2 shows the results of an OVERLAY from VIEW_A to VIEW_B. the data is divided differently into fields. 9-16 Assignment Statements . However. OVERLAY is left justified. If VIEW_A was as shown. Figure 9-2 Results of OVERLAY VIEW_A TO VIEW_B You can also OVERLAY a character expression to a view and a view to a character field. and A3: the strings ‘aaaaa’. and characters that exceed the length of an overlaid field are truncated. ‘bbbb’. and VIEW_B was a character field at least 18 characters long. which consist of the remaining three characters from A2 and the single character of A3. VIEW_B would end up with the same data in the same fields. B3 is defined to hold four characters: ‘bbbc’. VIEW_B would be set to ‘aaaaabbbbcdddeeeee’. the first ten characters of the stored representation of VIEW_A store the contents of the fields A1. and B3. but you encounter errors if you exceed the recommended length.Redefining a View with Another View Follow these steps to have a view redefine another view: 1. Note Java does not support redefining views. In this case. which copies the data from one area in memory to another thus creating two copies of the same data. Essentially. Double-click the relationship line between them to bring up the Edit view includes window. the two views are just different names for the same collection of data allowing you to use multiple definitions for the same memory space. Change the Null indicator property to Redefines View. 4. • The length of the second view must be less than or equal to the length of the first view. This is not enforced. Although these two views are created as parent and child. meaning that the data contained in the two views are stored at the same address in memory. Create a View Includes View relationship between the two views.Redefining Views ENDDCL and also includes the following view: Then the statements: MAP 'Hello' TO CHAR_VAR_1 MAP CHAR_VAR_1 TO VARCHAR_VAR_1 result in VARCH_VAR_1 containing ‘Hello’. where ?? stands for the ASCII value of the binary length of the VARCHAR variable. they are really clones—two names for the same view. Redefining Views You can have one view redefine another view. This is an alternative to overlaying views. Open the Construction Workbench and the Hierarchy window. the ASCII equivalent of binary 5 would be null-ENQ. Procedure . The following restrictions apply to using redefined views: • The first view cannot be a locally-declared view. AppBuilder 2. with the original view as the parent and the redefined view as the child.1 Rules Language Reference Guide 9-17 . Note 3. However.1. if you were to then use the following statement: OVERLAY VIEW_C TO CHAR_VAR_1 the variable CHAR_VAR_1 would contain ‘??HEL’. 2. Redefining Views 9-18 Assignment Statements . Upon completion.1.1 Rules Language Reference Guide 10-1 .CHAPTER 10 CONDITION STATEMENTS AppBuilder 2. C or Java) compiler possibilities. AppBuilder 2. These statements include: • IF Statement • CASEOF Statement • DO Statement Condition Statement Syntax if_statement caseof_statement do_statement IF Statement An IF statement routes control between two groups of statements.1. if there is no ELSE clause). You can nest IF statements. depending on the truth or falsity of a condition. If the condition is false.1 Rules Language Reference Guide Condition statements direct processing control within a rule to one group of statements or another depending on the value of a condition. The nest depth depends on the target language (COBOL. no statements are executed. If the condition is false and there is no ELSE. processing continues with the statement following ENDIF. If the condition is true. processing continues with the statements following the condition but before the ELSE clause (or before ENDIF. processing continues with any statements following the optional ELSE. IF Statement IF EVENT_SOURCE OF HPS_EVENT_VIEW = 'UPDATE' MAP CUSTOMER_DETAIL TO UPDATE_CUSTOMER_DETAIL_I USE RULE UPDATE_CUSTOMER_DETAIL ELSE MAP 'NO_CHANGE' TO RETURN_CODE OF DISPLAY_CUSTOMER_DETAIL_O ENDIF Example . Any Rules Language statement. 10-2 Condition Statements .CASEOF Statement IF Syntax IF condition statement ENDIF ELSE statement where: condition statement See “Conditions”.IF and Nesting IF Statements Example .Nesting IF Statements IF EVENT_SOURCE OF HPS_EVENT_VIEW='UPDATE' IF CUSTOMER_DETAIL <> UPDATE_CUSTOMER_DETAIL_I MAP CUSTOMER_DETAIL TO UPDATE_CUSTOMER_DETAIL_I USE RULE UPDATE_CUSTOMER_DETAIL ELSE MAP "No changes detected" TO UPDATE_STATUS OF CUSTOMER_WND_I ENDIF ELSE MAP 'NO_CHANGE' TO RETURN_CODE OF DISPLAY_CUSTOMER_DETAIL_O ENDIF CASEOF Statement A CASEOF statement routes control among any number of groups of statements. The CASEOF statement is a shorter way of expressing the same flow of control nested IF statements produce. depending on the value of a field. except a declarative statement Examples . where: symbol statement field_name See “Symbol”. a type with constants that can appear as a selector. of the literals or symbols in its subordinate CASE clauses equals the value in the field in the CASEOF clause.1 Rules Language Reference Guide 10-3 . Allowable types are: • Numeric • Character AppBuilder 2. static_field_name ) The last form of selector is available only in Java mode. no statements are executed.e. if any.1.CASEOF Statement A CASEOF statement determines which one. except a declarative statement name of the field of a suitable type. processing continues with the statement following ENDCASE. Processing continues with the statements following that CASE clause. Upon completion. If none of the CASE clauses equal the value in the field. Any Rules Language statement. CASEOF Syntax CASEOF field_name CASE selector statement ENDCASE CASE OTHER statement where selector has the following form: ‘character_literal’ numeric_literal symbol_name symbol_name IN set_name ( object_variable class_alias . If none of the CASE clauses equal the value in the field and there is no CASE OTHER clause. i. processing continues with the statements following the optional CASE OTHER. and OpenCOBOL modes.CASEOF statements In the statement CASEOF LETTER CASE 'A' 'E' 'I' 'O' 'U' 'a' 'e' 'i' 'o' 'u' MAP 'Vowel' TO LETTER_TYPE CASE 'Y' 'y' MAP 'Sometimes vowel' TO LETTER_TYPE CASE OTHER MAP 'Consonant' TO LETTER_TYPE ENDCASE the character field LETTER_TYPE is set to one of the character literals ‘Vowel’. the CASE clauses need not contain or cover all possible values. In Java. The statement CASEOF YEARS_AS_EMPLOYEE CASE 5 MAP 'Certificate' TO BONUS_ITEM 10-4 Condition Statements . The available selector types are listed in Table 10-1. or ‘Consonant’.CASEOF Statement Usage The literals or symbols in the CASE clauses must be compatible with the type of the field in the CASEOF clause. ‘Sometimes vowel’. Table 10-1 Selector types for field_names field_name CHAR Selector CHAR MIXED DBCS X x MIXED X X DBCS Conversion function Conversion function X Conversion function X A literal or symbol can appear only once within the CASE clauses of a single CASEOF statement. Example . it is illegal to have: CASE 5 statements CASE 5 statements in the same CASEOF statement. If rule call is intended. ClassicCOBOL. field_name can be CHAR. Such an ambiguity is always resolved in favor of set symbol. Also note that when a symbol has the same name as a rule. However. code this: CASE AMBIGUOUS_NAME USE RULE AMBIGUOUS_NAME rather than this: CASE AMBIGUOUS_NAME AMBIGUOUS_NAME For specific considerations refer to “CASEOF in Java”. MIXED. depending on the value of the character field LETTER. a CASE clause is case-sensitive. Thus. In addition. For example. as with any use of a string literal. an ambiguity can arise in a case statement as to whether the symbol is meant or a rule. or DBCS type. then USE RULE statement should be used. 1. CASEOF TRANS_CODE CASE 'A' 'C' statement statement CASE 'M' 'U' statement CASE 'X' statement statement CASE OTHER statement ENDCASE 1 2 3 4 5 6 The IF statement equivalent of the above is: IF TRANS_CODE = 'A' OR TRANS_CODE = 'C' statement 1 statement 2 ELSE IF TRANS_CODE = 'M' OR TRANS_CODE = 'U' statement 3 ELSE IF TRANS_CODE = 'X' statement 4 statement 5 ELSE statement 6 ENDIF ENDIF ENDIF DO Statement A DO statement provides control for repetitive loops. The following shows a skeleton example of the use of a CASEOF construct along with the semantically identical translation to a set of nested IF statements.1 Rules Language Reference Guide 10-5 . AppBuilder 2.DO Statement CASE 10 MAP 'Plaque' TO BONUS_ITEM CASE 25 MAP 'Watch' TO BONUS_ITEM ENDCASE sets BONUS_ITEM to the gift appropriate for an employee bonus after the indicated years of employment. If a DO statement contains a WHILE clause. control passes from the WHILE clause to the statement following the ENDDO. any statements between DO and ENDDO are executed repetitively as long as the condition in the WHILE clause is true and the TO bound is not reached. When one of conditions mentioned becomes false. However. Note that the WHILE clause can be at the top of the loop. INDEX clause • Specifies the name of a variable to use as the counter. Its value changes with each execution of the loop. control passes from the WHILE clause to the statement following the ENDDO. but the ending value of a counter is reached (see TO clause).DO Statement DO Syntax DO FROM numeric_expression BY numeric_expression INDEX TO numeric_expression field_name statement ENDDO WHILE condition statement where: condition numeric_expression statement See “Conditions”. BY clause • Specifies how much to increment the counter with each execution of the loop. Any Rules Language statement. When the condition becomes false. any statements between DO and ENDDO are executed repetitively as long as the condition in the WHILE clause is true. Nevertheless. 10-6 Condition Statements . A DO statement does not have to contain a WHILE clause. See “Numeric Expressions”. if the WHILE condition is true. or anywhere in the middle. it must contain at least one of the following four counter clauses that govern execution of the loop: FROM clause • Specifies the starting value for a counter. TO clause • Specifies the ending value of a counter. at the bottom of the loop. If a DO statement contains a WHILE clause. if it does not. except a declarative statement Usage A DO statement provides control for repetitive loops. the loop finishes and control passes from the WHILE clause to the statement following the ENDDO. 483. the loop is finished. This problem can only be seen in the following cases: • when FROM. Java and C support detection of the overflow condition for the loop index. Thus. and TO clause if you do not provide one. For example the execution of the following loops will never stop: DO TO 32767 ENDDO DO BY 3 TO 32765 ENDDO DO BY 100 ENDDO All of the above loops will have internal loop counter generated as 2 byte integer (SMALLINT type in Rules Language) which at some point will become a negative number because of the undetected overflow when adding BY value to the index. DO Statement Restriction When generating target code the goal is to produce the most efficient and the most readable code.766 • The INDEX clause is optional. TO. 5. The maximum value for the expression following TO is 2. Indexed DO Statements The following restrictions apply to an indexed DO statement: • It must contain at least one FROM. None of the target languages: Cobol.DO Statement A DO statement with one of these clauses is called an indexed DO. BY. a loop containing DO FROM 1 TO 10 BY 4 executes three times (for the values 1.1. BY. If it does not. • The expression following a FROM. a loop containing DO FROM 1 TO 10 executes ten times. the system converts the value to an integer by truncating it. • The system provides a default value for any FROM.647. Table 10-2 lists these default values.1 Rules Language Reference Guide 10-7 . BY and TO values are such that after iteration number N: BY > 0 and AppBuilder 2. Because of this restriction Rules Language also does not support overflow detection. using the constructions of the target language as much as possible. Thus.147. Table 10-2 System Default Values for Counter Clauses Statement FROM BY TO Default value 1 1 32. • The value in the TO clause is inclusive. the maximum value allowed in a field of type INTEGER. and BY clause must resolve to an integer value. and 9). or INDEX clause. TO. The system provides its own counter variable if you do not. If a BY clause forces the counter above the TO value. Example 4 DO FROM START_LEVEL INDEX COUNTER 10-8 Condition Statements . Example 1 DO WHILE TOTAL_AMOUNT > TOTAL_LIMIT statement 1 statement 2 MAP (TOTAL_AMOUNT .DO Statement FROM+BY*N <= TO and FROM+BY*(N+1) > MAX • or BY < 0 and FROM+BY*N >= TO and FROM+BY*(N+1) < MIN where MAX is the maximum value for the data type used for the index: 32767 for smallint. MIN is the minimum value for the data type used for the index.1) TO TOTAL_AMOUNT ENDDO The preceding DO statement executes statements 1 and 2 once before leaving the loop. Example 3 DO TO LOOP_END BY STEP_VAR INDEX COUNTER_VAR statement 1 statement 2 ENDDO The preceding DO statement executes from 1 to the value contained in LOOP_END by the value in STEP_VAR. Examples using DO Statements For the first two examples. 999 for DEC(3.1) TO TOTAL_AMOUNT ENDDO In this case. the preceding DO statement executes statements 1 and 2 twice before leaving the loop.0) and so on. assume that TOTAL_AMOUNT equals 2 and TOTAL_LIMIT equals 1 before the loop executes. Example 2 DO statement 1 statement 2 WHILE TOTAL_AMOUNT > TOTAL_LIMIT MAP (TOTAL_AMOUNT . 2147483647 for integer. incrementing COUNTER_VAR as it does so. the FROM loop controls processing.While the WHILE condition is true. When the WHILE condition becomes false.DO Statement statement 1 statement 2 WHILE CODES (COUNTER) <> TERM_CODE IN VALID_CODES ENDDO In the last example.1 Rules Language Reference Guide 10-9 . and then the condition for the WHILE loop is checked.1. the FROM clause and statements 1 and 2 execute. AppBuilder 2. control continues with the statement following the ENDDO. DO Statement 10-10 Condition Statements . These statements include: • USE Statements • CONVERSE Statements • RETURN Statement • PERFORM Statement • PROC RETURN Statement Transfer Statement Syntax use_statement converse_statement return_statement perform_statement proc_return_statement AppBuilder 2.1 Rules Language Reference Guide Transfer statements switch control of an application from one rule to another to perform another task.CHAPTER 11 TRANSFER STATEMENTS AppBuilder 2. Return statements return control to a rule. from a rule to a report to print the report. from a rule to a window to have the window appear on the screen.1 Rules Language Reference Guide 11-1 . or from a rule to an internal procedure.1.1. After it and any rules or components it calls finish processing.. DETACH Statement • USE RULE .. See “Numeric Value”.. INIT Statement • USE COMPONENT Statement USE Syntax rule_name USE RULE ( view aggregate expression . ) NEST INSTANCE file_name DETACH INSTANCE file_name INIT TERMINAL character_expression STARTTIME STARTINTERVAL numeric_value OBJECT field_name where: character_expression expression numeric_value view See “Character Expressions”.USE Statements USE Statements A USE statement transfers the logic flow of an application to another rule or to a component. You can now specify the input view directly in a RULE call. See “Numeric Expressions”.. See “View”.. control returns to the calling rule. DETACH OBJECT Statement in Java • Passing Data to a Rule • USE RULE . The called rule or component then directs control of the application.. NEST Statement • USE RULE ... This topic includes: • USE RULE Statement • USE RULE . 11-2 Transfer Statements . The calling rule resumes processing at the statement after the USE statement that invoked the called rule or component. A rule can always use another rule if they both have the same execution environment. but is modeless. another rule.1 Rules Language Reference Guide 11-3 . except as Table 11-2 shows. An INSTANCE clause after a USE RULE…DETACH statement allows “multiple occurrences” of the same window to be displayed at the same time. Any window the called rule converses is still nested. view or procedure hides the rule name. Notes for USE RULE When a rule is invoked data items initialization is performed. a user may switch between that window and any other currently visible window at any time by simply selecting something in the desired window. If you attach a rule to a configuration unit (via its parent process). the rule’s execution environment is that of the machine entity that is associated with the configuration unit. Thus. refer to “Initialization”. the windows displayed to the user are “nested” one on top of the other. Invoking Subrules Rules Language provides two methods to invoke subrules: • USE RULE statement • a “procedure call”-like expression If a field. • A USE RULE…INIT statement spawns an independently running AppBuilder host online rule. it can still normally be used in a USE RULE statement. but instructs the called rule to overlay its window over other windows of the application that are currently visible. users cannot return to the previous window until they perform some action in that window. or calls. the execution environment specified for the configuration unit overrides the execution environment specified for any rule attached to the configuration unit.1. For details on data items initialization. When you prepare a rule in configuration mode (using configuration units). • For more information. • A USE RULE…NEST statement invokes another rule. That is. However. that is. see “Use Rule Statement in OpenCOBOL” The using clause is optional depending on the existence of an input and/or an output view. Table 11-1 shows the abbreviations used in Table 11-2 Note Table 11-2 shows the possible combinations of rule using rule when each rule’s execution environment is specified as an attribute of the rule. Refer to “Event-driven Processing” in Developing Applications Guide for more information. You can also specify a rule’s execution environment by using configuration units. Its window is modal. A window conversed by a detached rule is also called a modeless secondary window. all other windows in its application are removed before its window appears. The called rule defines the input and output views in its linkage section and creates the linkage using the procedure division statement. • A USE RULE…DETACH statement invokes another rule and instructs the called rule to share control with the calling rule. AppBuilder 2.USE Statements USE RULE Statement A USE RULE statement transfers control to. a rule generally cannot use a rule with a different execution environment. A nested window is also modal. There are several variations of the USE RULE statement: • A simple USE RULE statement invokes another rule without any special instructions. If the called rule converses a window. This combination runs but is not recommended because it is not portable. This combination runs but is not recommended because it is not portable. because that setting causes a significant performance degradation. If the calling rule is Batch.USE Statements You can prepare client-side rules of a distributed application without using configuration units only if the client HPS.INI variable [AE runtime] ALWAYS_USE_DNA is set to YES at runtime. this kind of rule is treated like an IBM Mainframe (IMS) rule Table 11-2 Rule Using Rule Support Called Rule Calling rule PC PCCICS on PC PCCICS on MVS CICS CICS&Batch Batch IMS PCIMS on PC PCIMS on MVS Y=Yes (valid combination) 1 PC Y Y3 N N N N N Y3 N PCCICS on PC Y Y N N N N N Y N PCCICS on MVS Y Y Y Y3 N N N Y Y CICS Y Y Y Y W2 N N N N CICS& Batch Y1 C C C Y1 B N N N Batch N N N N W2 Y N N N IMS Y Y N N N N Y Y Y PCIMS on PC Y Y N N N N N Y N PCIMS on MVS Y Y N N N N Y3 Y Y C=CICS B=Batch N=No (invalid combination) W=Warning (valid but use caution) The way a called rule with an execution environment of CICS&Batch is executed depends on its calling rule. If the called rule is prepared instead on a workstation. PC & IBM Mainframe (CICS) PC & IBM Mainframe (CICS) IBM Mainframe (CICS) IBM Mainframe (CICS & Batch) IBM Mainframe Batch (MVS) IBM Mainframe (IMS) PC & IBM Mainframe (IMS) PC & IBM Mainframe (IMS) Explanation Workstation online rule When prepared on a workstation. therefore. depending upon the environment of the calling rule Batch mode under MVS MVS host online rule When prepared on a workstation. then it cannot be called from the host rule because a host rule cannot call a workstation rule. Table 11-1 Execution Environments Abbreviation PC PCCICS on PC PCCICS on MVS CICS CICS&Batch Batch IMS PCIMS on PC PCIMS on MVS Execution environment PC Workstation. the called rule is executed as a CICS program. If the calling rule is prepared instead on the MVS host. 2 3 4 11-4 Transfer Statements . then the execution mode of the called rule is determined by going up the application hierarchy until a calling rule is found that is either online or Batch. or CICS). If the calling rule is itself CICS&Batch. this kind of rule is treated like an IBM Mainframe (CICS) rule MVS host online rule Either MVS batch or CICS. this kind of rule is treated like a PC Workstation rule When prepared on the host. A warning is issued if a CICS&Batch rule calls either a CICS rule or a Batch rule. this kind of rule is treated like a PC Workstation rule When prepared on the host. then it cannot call the PC rule because a host rule cannot call a workstation rule. We recommend using it only in a development environment while testing small portions of your application. A Batch rule calls a PCCICS rule which calls a CICS rule. the following combinations can result but would not run: An online rule calls a PCCICS rule which calls a Batch rule. PCCICS. the called rule is executed as an MVS batch program. If the calling rule is online (PC. This is because a CICS&Batch rule inherits its execution mode from its calling rule (see note 1). There is no imposed limit on the number of windows that can be nested on a workstation. DETACH Statement As with NEST. USE RULE . you can nest only one window. • Detached rules cannot use Dynamic Data Exchange (DDE). before it invokes UPDATE_CUSTOMER_DETAIL. although memory determines the practical limit.USE Statements USE RULE .1. Both the calling rule and the called rule must be PC Workstation rules.. DISPLAY_CUSTOMER_DETAIL maps either ‘UPDATE’ or ‘NO_CHANGE’ into its own output view. An INSTANCE clause creates a unique instance of the rule. a MIXED field. a literal. However. which stores the data from CUSTOMER_DETAIL to a file. as shown in the following example: MAP CUSTOMER_DETAIL TO UPDATE_CUSTOMER_DETAIL_I USE RULE UPDATE_CUSTOMER_DETAIL IF RETURN_CODE1 OF UPDATE_CUSTOMER_DETAIL_O <>'FAILURE' MAP 'UPDATE' TO RETURN_CODE OF DISPLAY_CUSTOMER_DETAIL_O ENDIF If the HPS_EVENT_VIEW registers that the Update menu choice is selected. NEST Statement Use NEST only with a rule that converses a window. the input view of the rule UPDATE_CUSTOMER_DETAIL.1 Rules Language Reference Guide 11-5 . Passing Data to a Rule AppBuilder Rules Language supports two methods of passing data to a rule invoked with a USE RULE statement: • Mapping Data to the Input View • Passing Data in the USE RULE Statement Mapping Data to the Input View One method of passing data to a rule is to map the data into the called rule’s input view in a previous assignment statement. the rule calls UPDATE_CUSTOMER_DETAIL. In 3270 Converse applications... Typically. the rule maps the data from the window view CUSTOMER_DETAIL into UPDATE_CUSTOMER_DETAIL_I. or a character field up to 30 characters long. AppBuilder 2. The character value in the INSTANCE clause is the instance name and must be a set symbol. The following restrictions apply to detached rules: • There can be only five levels of detached rules. use DETACH only with a rule that converses a window. 15 nested windows is a practical limit. to tell the rule that called it whether the data from the window have been stored.. • 3270 Converse applications do not support modeless windows. 0) *>NEW MAP MAP USE VARIANT 2<* I1 TO P1 OF V I2 TO P2 OF V RULE INTEGER_SUM (V) *>NEW VARIANT 3<* USE RULE INTEGER_SUM (2*I1. MVS means either CICS or MVSBAT. Another rule can invoke INTEGER_SUM as follows: DCL I1. is inherited from the caller of RULE_1. I2 INTEGER.USE Statements Passing Data in the USE RULE Statement A second method of passing data to a rule is to include the data in the USE RULE statement itself. and also RULE_1. the MVS rule or component RULE_2 is to be executed as a CICS program. and res.” RULE_1. the online or batch nature of RULE_2. 0) Restrictions on Use Whether RULE_1 can use RULE_2 depends on the execution environments of both the “caller. RULE_2 is to be executed as an MVSBAT program. P2. *>OLD VARIANT<* MAP I1 TO P1 OF INTEGER_SUM_IO_VIEW MAP I2 TO P2 OF INTEGER_SUM_IO_VIEW USE RULE INTEGER_SUM *>NEW VARIANT 1<* USE RULE INTEGER_SUM (I1. For example. and IMS are online environments. depending on the nature of the caller. If RULE_1 is MVSBAT. CICS. Table 11-3 Rules Using Rules Called Rule type Calling Rule Type PC CICS MVSBAT PC Y N N CICS Y N N MVSBAT N N Y MVS Y O B IMS Y N N Y=Yes (valid combination) N =(invalid combination) O=Online B=Batch W=Warning (valid but use caution) 11-6 Transfer Statements . If RULE_1 is MVS. MVSBAT is a batch environment. Table 11-3 shows the possible interrelationships between what kinds of rules can use what kinds of rules—in terms of the execution environment. If the caller RULE_1 is online. suppose the rule INTEGER_SUM has an input/output view named INTEGER_SUM_IO_VIEW containing the integers p1. and the “called. The choices of execution environments are: • PC (also referred to as “Workstation”) • CICS (host online) • MVSBAT (pure batch mode under MVS. p2.. executed through JCL) • MVS (rules/components that can be used either in MVSBAT or CICS mode) • IMS PC. V VIEW CONTAINS P1. ENDDCL ..” RULE_2. RES. 34*I2. I2. The numeric value within the clause indicates the time when the rule starts to execute.. STARTTIME. with one of the IBM mainframe execution environments. • A STARTTIME clause indicates a specific time for the execution of the initiated rule. USE RULE . The numeric values in the STARTTIME and STARTINTERVAL clauses is the concatenation of three non-negative integers—hh. • A STARTINTERVAL clause delays the execution of the initiated rule. or IMS. the AppBuilder application execution system knows both an online executable file and also a batch executable file of RULE_2. a PCIMS rule is the same as a PC rule if prepared on a workstation and an IMS rule if prepared on the host. INIT Statement A USE RULE…INIT statement initiates the execution of the called rule (and any rules and components it calls) and causes the called rule to run independently from the calling rule.If the callerRULE_1 is PC. and STARTINTERVAL clauses because they can be assigned dynamically. For example: MAP 'Nonsense Terminal ID' TO TERMINAL_ID MAP -25616199 TO START_TIME USE RULE RULE200 INIT TERMINAL TERMINAL_ID AppBuilder 2.1 Rules Language Reference Guide 11-7 . For purposes of Table 11-4. The numeric value within the clause indicates how long from the execution of the statement until the rule starts to execute. mm. a rule that has an environment of PCCICS is the same as a PC rule if prepared on a workstation and is the same as a CICS rule if prepared on the host. only the first four characters are recognized. CICS & Batch. ss—such that: • hh is between 0 and 23 (hours) • mm is between 0 and 59 (minutes) • ss is between 0 and 59 (seconds) Notes for USE RULE…INIT The AppBuilder code generator cannot validate TERMINAL. If the MVS rule RULE_1 uses a CICS rule or an MVSBAT rule.1. the online version of RULE_2 is invoked. Likewise. The character value within the clause is the ID of the terminal. The initiated rule must be a host online rule (with which it has an existing relationship). code generation prompts you with a warning if RULE_1 is in Online mode and RULE_2 is in MVSBAT mode or vice versa.USE Statements Table 11-3 Rules Using Rules Called Rule type Calling Rule Type MVS IMS PC N N CICS W N MVSBAT W N MVS Y N IMS N Y Y=Yes (valid combination) N =(invalid combination) O=Online B=Batch W=Warning (valid but use caution) Note If RULE_2 is MVS. either CICS. You can initiate a rule on only one terminal with each USE RULE…INIT TERMINAL statement.. You can use a USE RULE…INIT statement by itself or with the following clauses: • A TERMINAL clause specifies the terminal on which the initiated rule is to run. and that terminal must be signed on at the time the statement is executed. or IMS. Table 11-4 summarizes whether a rule of one processing type can use a USE RULE…INIT statement to call a rule of another processing type. However. Meanwhile. A DL/I Batch rule in an IMS environment initiated by a USE RULE…INIT statement cannot contain another USE RULE…INIT statement within it.USE Statements STARTTIME START_TIME Note The preceding rule would prepare cleanly. The TERMINAL. because the IMS Run Control program starts a batch job member for each call. processing does not start with the root PROC_200. Do not use a USE RULE…INIT statement for multiple calls to a batch rule in IMS. in turn. CICS Execution Environment A CICS rule can initiate only a CICS rule or a CICS and Batch rule. the statement (coded within rule RULE_110): USE RULE RULE_210 INIT initiates the execution of RULE_210. IMS Execution Environment In IMS. and so on. Use a USE RULE statement instead. then returns control to RULE_100. which. can use other rules and components. RULE_210 does not return control to RULE_110. execution of RULE_110 proceeds independently: RULE_110 uses COMP_111. You cannot combine the TERMINAL clause with either the STARTTIME or STARTINTERVAL clauses. STARTTIME. Table 11-4 IMS Rule Processing Types Called Rule Processing Type Calling Rule Processing Type MPP Conversational BMP DL/I Batch MPP Y Y Y N Conversational N Y N N BMP Y Y Y N DL/I Batch Y Y Y N Y=Yes (can call) N=No (cannot call) Example . but might encounter problems at run-time. rules have a processing type in addition to an execution environment. RULE_110 continues to operate independently. and STARTINTERVAL clauses are not supported for rules operating under IMS. CICS and Batch. CICS and Batch Execution Environment An mainframe rule can initiate only a CICS rule or a CICS and Batch rule. then RULE_112. Other conditions and restrictions for using a USE RULE…INIT statement depend on the execution environment of the initiating rule. 11-8 Transfer Statements .USE RULE…INIT Given an application consisting of the entities and relationships shown in Figure 11-1. RULE_210 uses COMP_211 and RULE_212. but rather with RULE_210. either CICS. AppBuilder 2. for example. Refer to System Components Guide for more information on using components provided with AppBuilder. such as C or COBOL. to have RULE_210 start at 3:00:41 PM. A component is a programming module that is coded in some language other than the Rules Language.USE Statements Figure 11-1 Sample Hierarchy for USE RULE. change the USE RULE statement to read: USE RULE RULE_210 INIT STARTTIME 150041 To link the forked-off processing of RULE_210 to a specific workstation ID. Note Preparing a C language component which has a host execution environment creates only an MVSBATCH executable. 3270 converse mainframe system components are not supported for OpenCOBOL.1. change the USE RULE statement to read: USE RULE RULE_200 INIT TERMINAL 'wwww' USE COMPONENT Statement A USE COMPONENT statement passes processing control to a component. Refer to Developing Applications Guide for more information on components you write yourself.. change the USE RULE statement to read: USE RULE RULE_210 INIT STARTINTERVAL 040008 Alternatively..1 Rules Language Reference Guide 11-9 .INIT To have RULE_210 start after 4 hours and 8 seconds. ‘wwww’. AppBuilder generates the call differently for each target depending on how the user component accepts its parameters. However. AppBuilder provides flag settings according to the component’s target environment (CICS or BATCH). all the receiving components in the hierarchy must be coded in the same manner. Using this setting ensures that all previously written components will work as before.USE Statements A rule can always use a component if they both have the same execution environment. To retrieve the address of working storage. 11-10 Transfer Statements . In OpenCOBOL. so if you generate a component call. AppBuilder populates the input/output view address. The execution environments on the table include: • PC (also referred to as “Workstation”) • CICS (host online) • MVSBAT (pure mainframe batch mode) • MVS (component that can be used either in MVSBAT or CICS mode) • IMS • Java Table 11-5 Rules Component Support Components Rules PC CICS MVSBAT MVS IMS Java PC Y N N N N Y CICS N Y N W N N MVSBAT N N Y W N N C=CICS MVS Y C B Y N N B=Batch IMS N N N N Y N Java N N N N N Y Y=Yes (valid combination) N=No (invalid combination) W=Warning (valid but use caution) User Components in ClassicCOBOL and OpenCOBOL ClassicCOBOL calls user components using the HPSCOMMAREA. AppBuilder generates a contained program that receives the working storage view as a parameter and then uses ADDRESS OF to pass the pointer back to the calling rule. This pointer then populates the INPUT/OUTPUT view pointer in the commarea. Each target environment flag has three settings: • Y Setting • N Setting • B Setting Y Setting The Y setting passes the parameters DFHEIBLK and HPSCOMMAREA. The global flag is used during COBOL generation to specify the generation of the HPSCOMMAREA or a dynamic COBOL call. a rule generally cannot call a component with a different execution environment except as shown in Table 11-5. The parameters are global. the generated calling convention is optional to avoid changing every user component. as it is done in standard COBOL. If you are calling CICS components that initiate CICS calls. Calling Rule: CALL ‘GETADDR’ INPUT-VIEW.1 Rules Language Reference Guide 11-11 . INPUT-VIEW-PTR MOVE VIEW-ADDRESS OF INPUT-VIEW TO IV-ADDRESS OF RULE-COMP-COMMAREA. INPUT-VIEW. RULE-COMP-COMMAREA. 03 IN-DATA PIC X(80).INPUT-VIEW. INPUT-VIEW. Called Component: PROCEDURE DIVISION USING DFHEIBLK. which by default puts the DFHEIBLK and DFHCOMMAREA on the PROCEDURE statement and LINKAGE SECTION. END PROGRAM JMDADDR. IDENTIFICATION DIVISION. CALL ‘ABCDEF’ USING DFHEIBLK.USE Statements The contained program is embedded in the main program and delimited by the IDENTIFICATION DIVISION and END PROGRAM statements. Called Component: PROCEDURE DIVISION N Setting The N setting passes the INPUT and OUTPUT view as parameters. 01 INPUT-VIEW. AppBuilder needs this option for components that run through the CICS translator. The Commarea creates an artificial 1 byte parameter.1. OUTPUT-VIEW. PROGRAM-ID. OUTPUT-VIEW Called Component: PROCEDURE DIVISION USING INPUT-VIEW. GETADDR. ensure that the CICS translator uses the NOLINKAGE option. DATA DIVISION. SET VIEW-ADDRESS-PTR TO ADDRESS OF INPUT-VIEW. Calling Rule: CALL ‘ABCDEF’ USING INPUT-VIEW. RULE-COMP-COMMAREA. A separate contained program must be built for each view address needed. The component must establish addressability to the EIB. PROCEDURE DIVISION USING VIEW-ADDRESS-PTR. OUTPUT-VIEW B Setting The B setting passes a surrogate DFHEIBLK and DFHCOMMAREA along with an input/output view. Calling Rule: CALL ‘ABCDEF’ USING DFHEIBLK. OUTPUT-VIEW AppBuilder 2. Use the same parameters for the calling components PROCEDURE DIVISION statement. MOVE VIEW-ADDRESS OF OUPUT-VIEW TO OV-ADDRESS OF RULE-COMP-COMMAREA. LINKAGE SECTION.RULE-COMP-COMMAREA. 01 VIEW-ADDRESS-PTR POINTER. If the report has no sections attached. Is a character value containing the printer name. control automatically returns to the rule containing the CONVERSE statement. A CONVERSE statement performs one of the following actions: • Displays a window. • Blocks a rule until it receives an event. • Prints a report or portion of a report. Note Global views.CONVERSE Statements CONVERSE Statements This topic includes: • CONVERSE WINDOW Statement • CONVERSE REPORT Statement • CONVERSE for Global Eventing CONVERSE Syntax CONVERSE WINDOW window_name NOWAIT REPORT report_name PRINTER SECTION printer_name section_name numeric_value START SUBHEADER SUBHEADER END numeric_value OFF where: numeric_value priner_name report_name section_name START See “Numeric Value”. CONVERSE. CONVERSE WINOW. See “Character Value” Is the name of the report which belongs to the current rule. 11-12 Transfer Statements . Is the name of the section which belongs to the report (report_name). Upon completion of these actions. and CONVERSE REPORT are not supported in OpenCOBOL. START is optional. CONVERSE Statements CONVERSE WINDOW Statement Note CONVERSE WINDOW is not supported in Java. execution remains on the CONVERSE WINDOW statement until an event is returned to the rule. Manipulating a control object on the window interface generates a user interface event. A system event or an event from a parent or child rule also causes a rule to leave its waiting state. Notes for CONVERSE WINDOW A given rule can have a converse relationship with only one window. You can converse on the host in ClassicCOBOL mode and on a workstation in Java mode. a CONVERSE WINDOW statement “waits” for an event and then continues with the rule’s execution. In other words. NOWAIT A CONVERSE WINDOW…NOWAIT statement causes the AppBuilder environment to converse a window and return control immediately to the rule containing the statement. Examine the fields in the rule’s HPS_EVENT_VIEW view to decide what further action to take. Conversing a single section might produce as little as a single line of a report. This returns control to the rule. each of which includes layout data for part of the report. 3. 2. CONVERSE REPORT Statement A rule can control the printing of a report by conversing a report entity. Note This section applies to ClassicCOBOL and Java modes only. it does not wait for an event before continuing to process the rule.CONVERSE WINDOW Use a CONVERSE WINDOW statement in the following series of actions: 1. while a rule can have more than one CONVERSE WINDOW statement. The CONVERSE WINDOW statement causes the named window entity’s panel to display on the screen. It is not supported in C or OpenCOBOL. Thus. Refer to Developing Applications Guide for a detailed explanation of events and eventdriven processing. When printing reports on the host or on the workstation in Java mode. Procedure . In the rules code. each statement must refer to the same window. each report entity contains one or more section entities. Map the data in the fields in the window to the window’s input view. allowing a user to manipulate the window’s interface and field data. Converse the window. AppBuilder 2.1. In other words. You can print a whole report by issuing a series of CONVERSE REPORT statements.1 Rules Language Reference Guide 11-13 . A rule can map data into the view of a section and converse the report that contains that section to print the section’s data. . OFF A CONVERSE REPORT…SUBHEADER OFF statement dynamically resets to zero any subheader sequence number that is at least as big as the value following SUBHEADER. In order to print in CICS.. END statement on host and Java mode on the workstation.START statement initiates the printing of a report. Notes for CONVERSE REPORT A rule executing a CONVERSE REPORT statement temporarily relinquishes control to the report. SUBHEADER A CONVERSE REPORT…SECTION…SUBHEADER statement dynamically alters the subheader level number of the named section at execution time to the value in the SUBHEADER clause. A CONVERSE REPORT…START statement sets up global storage for the named report. On the workstation in Java mode. The section retains this new number until another such statement redefines the number. it returns information to the calling rule in a special view called the Report Communication Area 11-14 Transfer Statements .CONVERSE Statements START and PRINTER A CONVERSE REPORT. if you do not issue a CONVERSE REPORT . a CONVERSE REPORT…END statement releases the global storage that was allocated in the corresponding CONVERSE REPORT…START statement. In other words.. On the host. the last page of the report won't be printed.. SECTION Adding this keyword to a CONVERSE REPORT statement prints the named section’s data. It is a good practice to finish printing the report with CONVERSE REPORT . the report ends. any regular section with a subheader sequence number greater than or equal to this value loses the subheader property. A rule must contain one of these statements before any other CONVERSE REPORT statements. or a CONVERSE REPORT…SUBHEADER OFF statement is executed. which is needed in all of the other CONVERSE REPORT statements. You do not need this to print a batch or Java report. On the host and in Java mode on the workstation. when the report finishes processing the statement. A rule should contain one of these statements after all other CONVERSE REPORT statements... END in the rule. You can get a system abend without this statement. For additional information refer to “START and PRINTER in Java”. END A CONVERSE REPORT…END statement prints the final break sections and terminates the printing of a report. you must include the PRINTER keyword and specify a four-character printer name after it. This may lead to some undesirable side effects if you use the same report in this application again. Lack of this statement does not cause an abend but you are not alerted to the fact that the final break section is missing. use the following statement instead: CONVERSE REPORT CUST_SALES_TRANS PRINTER MAIN_PRINTER_4 START After you have started printing. CONVERSE for Global Eventing Global eventing provides a mechanism for passing messages among rules on the same or different systems. AppBuilder 2. with sections called RETAIL_CUST and WHOLESALE_CUST. Similarly.CONVERSE Statements (RPTCA). You should not change the RPTCA (assuming you have the authorization). If this is a batch report. use the following statement to start printing the report: CONVERSE REPORT CUST_SALES_TRANS START If this is a CICS report. if you have distributed printing over more than one rule.1. any client rule that includes the same event in its hierarchy receives and processes the message. and that you want to print it on a host printer called MAIN_PRINTER_4. you can insert other CONVERSE REPORT statements as needed for your report. CONVERSE REPORT CUST_SALES_TRANS SECTION RETAIL_CUST CONVERSE REPORT CUST_SALES_TRANS SECTION WHOLESALE_CUST These statements print both sections of the report. CONVERSE REPORT CUST_SALES_TRANS SUBHEADER 2 OFF This statement resets the subheader level of the RETAIL_CUST section (and any higher-numbered sections) to zero. CONVERSE REPORT CUST_SALES_TRANS END This statement prints the final break sections and ends printing. When one rule that includes an event in its hierarchy posts a message. If you have distributed the printing of a report over more than one rule in your application. CONVERSE REPORT CUST_SALES_TRANS SECTION RETAIL_CUST SUBHEADER 2 This statement resets the RETAIL_CUST section subheader level number to 2. not once per rule. Example of CONVERSE REPORT Assume you have a report called CUST_SALES_TRANS.1 Rules Language Reference Guide 11-15 . You can view the RPTCA in the enterprise repository as you would any other view. When an event is received. Issuing a subsequent CONVERSE REPORT…START statement restarts a report and resets the page and line numbers to one. because AppBuilder references its members for internal processing. the rule begins executing the statements following the CONVERSE. you need to issue a CONVERSE REPORT…END statement only once. Execution of a CONVERSE statement without a window or report has the effect of blocking a rule until an event is received. you need to issue a CONVERSE REPORT…START statement only once. not once per rule. A rule containing a CONVERSE WINDOW statement is unblocked upon receipt of global events as well as interface and system events—the statements following the CONVERSE begin executing when a global event is received. The code in rule RULE_2. A RETURN statement allows you to send control back to the calling rule before all lines in the called rule have been executed.RETURN Statements In the following sample code. Note A RETURN statement inside a procedure causes a return from the rule containing the procedure. Rule 1 : USE RULE RULE_2 MAP RULE_2O TO RULE_3I : Rule 2 CASEOF ACTION_TO_PERFORM OF RULE_2I CASE 'TEST' TEST(RULE_2I) MAP 'TESTED' TO STATUS OF RULE_2O RETURN CASE 'SKIP' RETURN ENDCASE 11-16 Transfer Statements . either performs a local procedure TEST and sets "return code" (STATUS field of RULE_2 output view) to 'TESTED' or returns processing control to RULE_1.RETURN Statement Note You can also use a CONVERSE WINDOW statement to receive global events. processing control returns to its calling rule only after the last statement in the called rule is executed. a portion of rule RULE_1 calls the rule RULE_2. If a called rule has no RETURN statement. RETURN Statement A RETURN statement sends processing control back from the rule in which it appears to the rule that called its rule. depending on ACTION_TO_PERFORM field of its input view. Note Global eventing is not supported in OpenCOBOL generation. if 'SKIP' operation is chosen by RULE_1. RETURN Syntax RETURN Example . Refer to the Developing Applications Guide for an explanation of global eventing. Use a PROC RETURN statement to return from the procedure to the point of invocation within the rule. If you pass a view to a procedure. That is. Note Normally. are passed by value only. AppBuilder 2. Therefore. The only exception to this rule are procedures without parameters. For additional information see “PERFORM Statement (PROC) in OpenCOBOL”. although the pointer itself is passed by value. you should use a PERFORM statement. or literals as parameters to a procedure. including views. You cannot pass an input/output parameter to a procedure. Parameters are input only. the view must be declared inside the procedure receiving it (see “Common Procedure”). rather than duplicating the statements of the procedure at multiple places in the rule. PERFORM statements allow you to invoke a procedure multiple times within a rule.1 Rules Language Reference Guide 11-17 . ( view aggregate expression ) where: expression view See Chapter 4. Note If you pass an object (see “Object Data Types”) as a parameter to a procedure. procedure must be defined before it is used. To invoke a procedure without parameters before it is defined. When the statements of the procedure finish executing. it still provides addressability to the object to which it points. PERFORM Syntax procedure_name PERFORM parameter_list where parameter_list can be: . objects used as parameters allow a procedure to modify objects other than those that are passed in as parameters. See “View”. PERFORM statement must be omitted. you cannot pass a variable to a procedure and expect it to be modified when the procedure returns.1. For all other cases.PERFORM Statement PERFORM Statement A PERFORM statement invokes a procedure within the same rule. views. Parameters. “Expressions and Conditions”. control is returned to the statement following the perform statement. PERFORM Usage You can pass individual data items. PROC cubed (inputNumber INTEGER): INTEGER PROC RETURN (inputNumber * inputNumber * inputNumber) ENDPROC . see “Abbreviating Rule Source”. If the procedure returns a value. For information. The procedure can be used in any context in which a function can be used—in this case in a MAP statement. but execution results will be unpredictable. the procedure is treated like a function and can be used in any context in which a function can be used. Warning Recursion is not supported for procedure calls in ClassicCOBOL or OpenCOBOL. MAP cubed(anyNumber) to y 11-18 Transfer Statements . There will be no error message if recursion is used. handleError(code) . Using a procedure as a function The following example illustrates using a procedure as a function.PERFORM Statement A procedure can return a value if that value is declared inside the procedure. handleError(dbCode) Note Another way to simplify rule source is to use a macro for frequently repeated code. ENDDCL IF errorCode <= 0 MAP "SUCCESS" TO errorDescr ELSE IF errorCode <= 2 MAP "WARNING" TO errorDescr ELSE MAP "SEVERE ERROR" TO errorDescr ENDIF ENDIF PRINT errorDescr ENDPROC . the coding of each process is simplified. PROC handleError(errorCode SMALLINT) DCL errorDescr VARCHAR(255). The procedure “cubed” receives one parameter (an integer) and returns the cube of that number.Error Code Processing and Procedures as Functions Simplifying error code processing The following example illustrates the use of a procedure to simplify multiple error code processing. PERFORM Examples . 1. it is the return value of the procedure as a function call. AppBuilder 2.PROC RETURN Statement PROC RETURN Statement A PROC RETURN statement causes a procedure to return control to the point immediately after the point from which the procedure was invoked (see Chapter 8.1 Rules Language Reference Guide 11-19 . PROC RETURN Syntax PROC RETURN ( view aggregate expression ) where expression is a valid expression (see “Expression Syntax”) and view is a valid view (see “View”). “ObjectSpeak Statement”). If an expression is included on the PROC RETURN. No further statements in the procedure are executed. PROC RETURN Statement 11-20 Transfer Statements . Macros are not supported on the mainframe.1 Rules Language Reference Guide A macro is a mechanism for replacing one text string in rule source with another one. The values are set according to the platform to which they are generating code as summarized in Table 12-1. Every word other than comments and quoted strings in the rule source is looked up in a dictionary before code is generated. the lookup is casesensitive. Control Statements. Only special quoted strings (see Using Quoted Strings in Macros) and Rules Language comments (see Chapter 8. AppBuilder 2. This replacement is termed macro expansion.1 Rules Language Reference Guide 12-1 . Unlike most Rules Language processing.INI). it is replaced by the macro definition. Topics about macros include: • Predefined Macros • Defining Macros • Declaring Constants • Abbreviating Rule Source • Using Conditional Macros • Macro Reference • Extensions of Macro Support Predefined Macros There are two predefined macro definitions that can be used in rules. You can use a macro in a rule prepared on any system other than the host.1. it must result in valid Rules Language code or an error occurs during code generation.1. regardless of the structure. Because expansion is done before code generation. If the word is recognized as the name of a macro.CHAPTER 12 MACROS AppBuilder 2. • LANGUAGE • ENVIRONMENT They are used only on the PC workstation. These macros are defined in the AppBuilder initialization file (HPS. its source is scanned character by character. Comment Statement) are not scanned. even string literals are not processed as a special case. When you prepare a rule. INI file. where the first character is not a digit. Macro expansion occurs automatically during rule preparation.) You can define a macro anywhere but the definition must occur before any use of the macro. “INIT” represents a different macro than “init. This generates: 12-2 Macros . Macro names are case-sensitive. and the underscore character (_). they are part of the replacement string and are included when the replacement string is substituted for the macro name. The resulting definition is local and available only for the rule where the macro is defined. string ) For example: CG_DEFINE( init. 2. use a definition statement of the following format: CG_DEFINE( macro_name . Defining Macros in Rules You can define macros for the rule in two ways: 1. for example.Defining Macros Table 12-1 Values for LANGUAGE and ENVIRONMENT Macros When generating Java client code Java server code for RMI or EJB Servlet client code for HTML client C code for client Windows application C code for server Windows application COBOL LANGUAGE= Java Java Java C C Cobol ENVIRONMENT= GUI Server HTML GUI Server Server Defining Macros To define a macro. The replacement string is not enclosed in quotes. digits. Note A comma used to separate any two operands in a macro statement must immediately follow the first operand with no intervening spaces. Blanks are not permitted. In the HPS. using one of two possible ways to define macros: • Define them in the [MacroDefinitions] section from Construction Workbench. as shown. MAP 0 TO HPS_WINDOW_STATE OF HPS_SET_MINMAX_I) macro_name is any sequence of letters. (If quotes are included. Use RuleView to see the results of macro expansion.” “CG_DEFINE” must be entered in capital letters. In the rule source using CG_DEFINE. string is any sequence of characters allowed in Rules Language. Spaces are permitted after the comma and before the second operand. • Define macros in the platform/language specific section of HPS. Declaring Constants One common use for macros is to declare constants. the value will be chosen depending on the target platform and language.1 Rules Language Reference Guide 12-3 . you can use it in any subsequent statement.1.14159) Once the constant is defined. Using a constant is preferable to using a variable because a constant allows the compiler to optimize statements referencing the constant. 3. so when the rule is prepared. AppBuilder 2.INI. For example. such as: MAP pi * (RADIUS**2) TO AREA Using a macro to declare a constant is good programming practice because it allows you to use a meaningful name for the constant rather than a number.Declaring Constants [MacroDefinitions] macro_name_1=macro value 2 CONVERSE_CLIENT=TRUE Note These macros will be available to all rules. For example: [CGen] MACRO=LANGUAGE=C MACRO=ENVIRONMENT=GUI [JavaGen] MACRO=LANGUAGE=Java MACRO=ENVIRONMENT=GUI [JavaServerGen] MACRO=LANGUAGE=Java MACRO=ENVIRONMENT=Server [JavaHTMLGen] MACRO=LANGUAGE=Java MACRO=ENVIRONMENT=HTML Two macros are defined in several sections. you can use the following macro definition to declare a constant for the value of pi: CG_DEFINE(pi. For example. to add 1 to any numeric variable. suppose that after each use of a system component you check the return code in the same way and invoke the same error routine in case of error: USE COMPONENT SET_PUSH_COLOR IF ( RETURN_CODE OF SET_PUSH_COLOR_O <> 0) USE RULE MY_REPORT_COMPONENT_ERROR ENDIF If you define a macro as: CG_DEFINE( check_return. When you prepare the rule. if your rule source uses the macro with a parameter: increment( QMAX) it becomes (after replacement): MAP QMAX + 1 TO QMAX The following example involves two invocations of the SET_PUSH_COLOR system component to set the color of the text in two push buttons. you can check the return code by using the macro: USE COMPONENT SET_PUSH_COLOR check_return Using Parameters Macros support parameters. In applications where lines of code are repeated frequently. where n is a number in the macro definition.Abbreviating Rule Source Abbreviating Rule Source The most common and powerful use of macros is to abbreviate rule source code. define the following macro: CG_DEFINE( increment. The only variants are the system identifier (HPS ID) of the push button. IF ( RETURN_CODE of SET_PUSH_COLOR_O <> 0) USE RULE MY_REPORT_COMPONENT_ERROR ENDIF ) then after every use of the system component. To define a macro parameter. you can define a macro and use the macro name in your code. Both invocations are highly repetitious. This consideration is important because recurring lines of code most frequently recur with some variation and are not identical. For example. AppBuilder replaces the macro name with the actual lines of code. Using parameters. MAP 'OK' TO PUSH_TEST OF SET_PUSH_COLOR_I MAP TEXT IN WINDOW_OBJECT_PROPERTIES TO PUSH_ATTR OF SET_PUSH_COLOR_I MAP GREEN in WINDOW_OBJECT_COLORS TO ATTR_COLOR OF SET_PUSH_COLOR_I USE COMPONENT SET_PUSH_COLOR IF ( RETURN_CODE OF SET_PUSH_COLOR_O <> 0) USE RULE MY_REPORT_COMPONENT_ERROR ENDIF 12-4 Macros . MAP $1 + 1 TO $1) Then. you can allow for variations and still use macros for repetitive tasks. and the color specified for each. use the string $n. The same is true for string literals. as follows: set_pushtext( 'OK'. RED) Macro Substitution Every identifier that is not in comments or in special quoted strings is looked up in a dictionary.1. MAP $1 TO PUSH_TEST OF SET_PUSH_COLOR_I MAP TEXT in WINDOW_OBJECT_PROPERTIES TO PUSH_ATTR OF SET_PUSH_COLOR_I MAP $2 in WINDOW_OBJECT_COLORS TO ATTR_COLOR OF SET_PUSH_COLOR_I USE COMPONENT SET_PUSH_COLOR IF ( RETURN_CODE OF SET_PUSH_COLOR_O <> 0) USE RULE MY_REPORT_COMPONENT_ERROR ENDIF ) then you can use the macro in place of the repetitious code. MY_RULE_NAME is not known as a macro name. If this identifier is equal to a previously defined macro name. system identifier (HPS ID) and color: CG_DEFINE( set_pushtext. this is not a special symbol. my_rule) //The following will be substitute ‘RULE_NAME’ “RULE_NAME” RULE_NAME% *>Percent sign is a special symbol. thus it is not a part of the identifier. For example: CG_DEFINE( RULE_NAME. RULE_NAME is in the middle of the identifier <* “RULE_NAME_1” *> This is also the case where RULE_NAME is only a part of another identifier RULE_NAME_1<* _RULE_NAME *>Underscore is a part of the identifier.1 Rules Language Reference Guide 12-5 . GREEN) set_pushtext( 'Cancel'. it is substituted with macro value. not any of its parts. so this will not be substituted either<* AppBuilder 2. RULE_NAME will be substituted and result string will be my_rule% <* //No substitution occurs in the following strings MY_RULE_NAME *> In this case.Macro Substitution MAP 'Cancel' TO PUSH_TEST OF SET_PUSH_COLOR_I MAP TEXT in WINDOW_OBJECT_PROPERTIES TO PUSH_ATTR OF SET_PUSH_COLOR_I MAP RED in WINDOW_OBJECT_COLORS TO ATTR_COLOR OF SET_PUSH_COLOR_I USE COMPONENT SET_PUSH_COLOR IF ( RETURN_CODE OF SET_PUSH_COLOR_O <> 0) USE RULE MY_REPORT_COMPONENT_ERROR ENDIF If you define a macro using a parameter in place of the two different features. however only the whole identifier is looked up. For example. for C mode. while the Java syntax is MAP TRUE TO BUTTON. preparing the rule with CG_IFELSE. ExitButton. Macro Reference The following sections contain detailed descriptions of macro syntax and use: • Using Quoted Strings in Macros • Changing the Quote Characters in Macros • Defining Macro Parameters • Using Special Parameters in Macros • Embedding Macros • Rescanning with Embedded Macros • Undefining a Macro • Using Conditionals in Macros 12-6 Macros . string1. a different syntax is used to set object properties for these languages.Using Conditional Macros Using Conditional Macros You can use macros to include conditional code in rule source.Enabled(1) to enable the button. MAP TRUE TO ExitButton. string2) When the macro is processed.Enabled) LANGUAGE is a predefined macro whose value is set to the platform where the rule is being prepared. For instance. as mentioned above. see “Using Conditionals in Macros”. Using a conditional macro.Enabled Since objects are not supported in COBOL mode. For example. string1 is inserted into the rule source. you can use a macro definition statement of the following form: CG_IFELSE(macro_name. you use BUTTON. this is exactly what you might want to have. you may want to use one rule for C and Java platforms. To code an “if. If equal.Enabled(1) For Java mode (prepared using "else" code). C. For additional forms of conditional macros. a comparison is made between the first and second operators. Of course. you might include the following macro statement in your rule source: CG_IFELSE(LANGUAGE. in C.else” type conditional macro. If not equal.. value. Thus. results in: ExitButton. the result is: MAP TRUE TO ExitButton.Enabled(1).Enabled. string2 is inserted.. to define the Enabled property of a push button object. you can write one rule for both platforms. <:This is quoted to prevent expansion:>) Changing the Quote Characters in Macros The default quote strings are <: to start the quotes and :> to finish them. For example. the whole quoting mechanism is turned off. These are intended to be unlikely to clash with normal Rules Language text. They may be changed at any time with a CG_CHANGEQUOTE statement. close ) where open is the string to start the quotes and close is the string to end the quotes. CG_CHANGEQUOTE(. 16) MAP 'quantity is quantity' TO C_TEXT this results in the clearly inappropriate statement: MAP '16 is 16' TO C_TEXT To prevent this. You can change the quotes to empty strings to disable the quoting mechanism entirely. To prevent substitution. By changing the quotes to empty strings. ') If one of the parameters is missing. If you write: CG_DEFINE( quantity. CG_CHANGEQUOTE( open. to use ' to open and to close.Macro Reference Using Quoted Strings in Macros Sometimes you do not want macro substitution to be performed on a string. Thus <:::> becomes an empty string and <:<:quantity:>:> becomes <:quantity:>. 16) MAP 'qu<:ant:>ity is quantity' TO C_TEXT achieves the same result. the default <: and :> are used instead. enclose the string within special quotes: “<:” at the beginning and “:>” at the end. 16) MAP '<:quantity:> is quantity' TO C_TEXT this results in the statement: MAP 'quantity is 16' TO C_TEXT Quote strings are recognized anywhere. so: CG_DEFINE( quantity. One level of quotes is stripped off as the rule is processed.1 Rules Language Reference Guide 12-7 .) AppBuilder 2.1. Note that it is commonplace to quote a macros definition to prevent expansion: CG_DEFINE( macroname. use the macro statement: CG_CHANGEQUOTE( '. Suppose you want to map both the name of a macro and its definition into a character variable. Special quotes may be nested. quote the first part: CG_DEFINE( quantity. where n is a number. then reinstating it. There is no such thing as an empty parameter list. You can circumvent this by disabling quoting temporarily. MAP $1 TO FIELD_LONG_NAME OF SET_CURSOR_FIELD_I MAP $2 TO VIEW_LONG_NAME OF SET_CURSOR_FIELD_I USE COMPONENT SET_CURSOR_FIELD) To use the macro. For example. This means that: macro_name (1. The first parameter is $1. b )##” expands to “##ab##”.’CUSTOMER_VIEW’) The “(” must be placed immediately against the macro name with no spaces in between. b )##” expands to “##a b ##”. Quote strings should never start with a letter or an underscore (_).2) is not a use of macro_name with two parameters but instead a use with no parameters followed by the string (1. Defining Macro Parameters A macro can have any number of parameters. Parameters are evaluated before the macro is called.Macro Reference A limitation of macro definitions is that there is no way to quote a string containing an unmatched left quote. $1$2) then: “##CAT( a. But “##CAT( a .2). Thus: macro_name() is really macro_name used with one parameter. the second $2. $0 is a special case which expands to the name of the macro being defined. if you define the following macro to join two strings: CG_DEFINE( CAT. To define a macro parameter. and so on. the extra ones are taken to be the empty string. Parameter lists are variable in length and if more parameters are expected than are provided. 12-8 Macros . an empty string. For example: CG_DEFINE( set_cursor_field. Spaces in parameter lists are significant after a parameter. use the following string in the macro definition: $n. specify the parameters enclosed within parentheses and separated by a comma: set_cursor_field(‘NAME_FIELD’. “*” or “@” is simply copied. This is quite subtle. Copied Parameters A “$” sign that is not followed by a digit or “#”. two)” expands to "Parameters are one. $#) the following expansions result: Macro use Result HowMany HowMany() HowMany( q. These include: • Number of Parameters . as the process of rescanning normally removes these quotes again.1 Rules Language Reference Guide 12-9 .$ and any character (except #. *.Macro Reference Using Special Parameters in Macros There are special (wild card) parameters that expand to cover a range of values. $$$$) amount expands to: $$$$ AppBuilder 2. @) Number of Parameters $# expands to the number of parameters provided when the macro is invoked.1.two" List of All Parameters Quoted $@ is the same as $* except all the parameters are quoted. given the following macro definition: CG_DEFINE( HowMany.$@ • Copied Parameters .$* • List of All Parameters Quoted . So. Parameters are $*) “All( one. so: CG_DEFINE( amount. So given: CG_DEFINE( All.r) 0 1 2 List of All Parameters $* expands to a list of all the provided parameters with commas between.$# • List of All Parameters . macros are not subject to the usual Rules Language constraints. when substitution takes place. 6) CG_DEFINE( turnred. the result is rescanned so that further substitution can be done. However. the macro preprocessor scans the rule source once. 10) CG_DEFINE( SETPROMPT. For example: CG_DEFINE(LISTSIZE. Because macro processing is done before code generation. the result of the code fragment is: MAP 6 TO BUTTON Rescanning can lead to a problem of infinite recursion.Macro Reference Embedding Macros Macro expansion takes place wherever the macro occurs. This can be prevented by use of nested quotes: CG_DEFINE( infinite. For example: CG_DEFINE(LISTSIZE. its expansion is two copies of itself. <:MAP red TO BUTTON:>) turnred The macro “turnred” uses the quotes to prevent the substitution for “red” before it is used. <:<:infinite infinite:>:>) infinite which results in: infinite infinite The extra level of quotes prevents the rescan from seeing the recursive use of infinite. There is no defined limit to the depth of such recursion. which are then expanded again (due to rescanning). This means that you can even use a macro inside a string. When turnred is used its substitution is “MAP red TO BUTTON” but the subsequent rescanning spots the macro “red” and substitutes “6”. and so on. 10) MAP 'Use LISTSIZE entries' TO F_PROMPT results in: MAP 'Use 10 entries' TO F_PROMPT Macros can also be used inside other macro definitions. Consider: CG_DEFINE( infinite. MAP 'Use LISTSIZE entries' TO F_PROMPT) SETPROMPT also results in: MAP 'Use 10 entries' TO F_PROMPT Rescanning with Embedded Macros Normally. Care must be taken to avoid this. In this example. 12-10 Macros . For example: CG_DEFINE( red . <:infinite infinite:>) infinite When infinite is expanded. If they are equal. CG_IFELSE( value1 . MAP 'DB2' TO DB. string . string ) The three parameter version compares value1 (which is typically the value of a macro) with value2 for string equality. The following macros cause different expansions depending on whether a particular macro is defined or not: CG_IFDEF( macro_name .1. note the use of quoting to prevent the macro from being expanded: Macro use Result CG_DEFINE( DB2) CG_IFDEF( <:DB2:>. you need to use quotes to prevent macro expansion within the CG_UNDEFINE statement. for example. use a statement of the following form: CG_UNDEFINE( macro_name ) Assuming the macro is already defined. the first string is substituted if the macro exists. MAP 'Default' TO DB) MAP 'Default' TO DB The following macro compares values and performs substitution based on the result of the comparison: .1 Rules Language Reference Guide 12-11 . To undefine a macro. so the string “map” is copied into the rule source (no substitution is performed). MAP '<:DB2:>' TO DB) MAP 'DB2' TO DB If two strings are specified. ) string If only one string is specified. Using Conditionals in Macros Several macro statements test conditions to allow decisions to be taken and alternate expansions selected. AppBuilder 2.Macro Reference Undefining a Macro Sometimes a macro needs to be undefined. it substitutes the third parameter. For example: CG_DEFINE( map. macro expansion takes place if macro_name exists. otherwise the second string is substituted: Macro use Result CG_UNDEFINE( <:DB2:>) CG_IFDEF( <:DB2:>. In the following example. to prevent macro expansion within a sequence of text containing the macro. <:MAP $1 TO C_TEXT:>) CG_UNDEFINE( <:map:>) map This results in “map” being undefined. value2 . DB. DB. DB. DB2. <:Informix:>. <:Informix:>. <:MAP 'DB2' TO DBASE:>) CG_DEFINE( DB. <:MAP 'DB2' TO DBASE:>. Using more than four parameters allows you to code a CASE-OF statement. DB2) CG_IFELSE( DB. <:MAP 'Oracle' TO DBASE:>. DB. if they are equal. otherwise it substitutes the fourth parameter. DB. Oracle) CG_IFELSE( DB. <:Oracle:>. DB2. <:MAP 'DB2' TO DBASE:>. then val1 and val2 are compared for string equality and. <:MAP 'Other' TO DBASE:>) MAP 'Oracle' TO DBASE MAP 'DB2' TO DBASE MAP 'Other' TO DBASE 12-12 Macros . DB. <:MAP 'Oracle' TO DBASE:>. <:MAP 'Informix' TO DBASE:>. <:MAP 'Sybase' TO DBASE:>. the first three parameters are stripped and the process repeats until no parameters are left. <:MAP 'Informix' TO DBASE:>. Sybase) CG_IFELSE( DB. the result is text1. if they are equal. <:Sybase:>. <:MAP 'DB2' TO DBASE:>) MAP ‘DB2’ TO DBASE The four parameter version compares val1 and val2 for string equality and. DB. Macro use Result CG_DEFINE( DB. Macro use Result CG_DEFINE( DB. <:DB2:>. <:Sybase:>. <:Oracle:>. <:MAP 'Sybase' TO DBASE:>) MAP 'DB2' TO DB MAP 'Sybase' TO DB If more than four parameters are passed. DB2. DB2. <:Informix:>. DB2) CG_IFELSE( DB. <:DB2:>. <:MAP 'Sybase' TO DBASE:>) CG_DEFINE( DB. <:MAP 'DB2' TO DBASE:>. <:MAP 'Sybase' TO DBASE:>. <:MAP 'DB2' TO DBASE:>. Sybase) CG_IFELSE( DB. <:MAP 'Informix' TO DBASE:>. substitutes the third parameter. <:Oracle:>. <:MAP 'Oracle' TO DBASE:>. <:DB2:>. <:Sybase:>. DB2) CG_IFELSE( DB. DB. DB. otherwise. <:MAP 'Other' TO DBASE:>) CG_DEFINE( DB. <:MAP 'DB2' TO DBASE:>.Macro Reference Macro use Result CG_DEFINE( DB. <:MAP 'Other' TO DBASE:>) CG_UNDEFINE( <:DB:>) CG_IFELSE( DB. <:MAP 'Sybase' TO DBASE:>. The following extensions are described: • Using Conditional Translation • Including Files • Exiting from Translation • Using Recursion to Implement Loops • Using String Functions • Using Arithmetic Macros Using Conditional Translation In its first occurrence in the syntax drawing below. else. CG_IF(macro_name. all statements after CG_ELSE are excluded from translation. Informix) Map 1 to i CG_ELSE Map 0 to i CG_ENDIF Because database was defined as Informix.1 Rules Language Reference Guide 12-13 . value ) ) statements CG_IFDEFINED CG_IFNOTDEFINED Macro_name CG_ENDIF CG_ELSE statements where: • macro_name is any macro name • value is any string that could be assigned to macro_name • statements is any Rules Language statement Example . only statements after CG_ELSE are processed. If they are equal. Macro IF Syntax CG_IF ( Macro_name ( .1. Informix) CG_IF(database. AppBuilder 2. the macro name compares with the value.Extensions of Macro Support Extensions of Macro Support A description with examples is provided for each extension of macro support.Conditional Translation CG_DEFINE(database. “Map 1 to i” is processed. value). TRUE) CG_IF(JAVA . For example. it is treated as "JAVA_" (underscore means space) and expanded into "TRUE_". For example: CG_DEFINE(JAVA. the preprocessor analyzes to determine if macro_name has not been defined. By default. only statements after CG_ELSE are processed. case-sensitivity is enabled to facilitate backwards compatibility. assume the following section exists in the HPS. In the second example. all statements after CG_ELSE are excluded from translation. If it has. Because "TRUE_" is not equal to "TRUE". "Map 0 to i" is processed. CG_IFDEFINED (macro name). Currently.INI file and the rule has been prepared for Java: 12-14 Macros . TRUE) *>Additional space after 1st parameter and before second one<* Map 1 to i CG_ELSE Map 0 to i CG_ENDIF Because of the extra space after the first CG_IF parameter. Case-sensitivity This configuration option (code generation parameter) controls the case-sensitivity of the macro preprocessor. The same logic applies for spaces before other parameters (second and so on). else. all statements after CG_ELSE are excluded from translation. CG_UNDEFINE(Java) CG_IFNOTDEFINED(Java) Map 1 to i CG_ELSE Map 0 to i CG_ENDIF Because Java was undefined. all macro values are case-sensitive. the preprocessor analyzes to determine if macro_name has been defined.Extensions of Macro Support CG_IF Additional Notes In order to achieve predictable behavior. do not place extra spaces after preprocessor command parameters because extra space is considered to be a part of a parameter. When this option is enabled. CG_IFNOTDEFINED(macro name). the preprocessor ignores the case of the macro value. only statements after CG_ELSE are processed. “Map 0 to i” is processed. Spaces are allowed just before parameters. CG_UNDEFINE(Java) CG_IFDEFINED(<:Java:>) Map 1 to i CG_ELSE Map 0 to i CG_ENDIF Because Java was undefined. else. “Map 1 to i” is processed. Only CG_IF is supported for this option. If it has been defined. In the third example. INI can also be used: FLAG=MEXCI Note Macro names are always case-sensitive. the listing will also contain the following error: ERROR: 52960-S Value "JAVA" is not listed in the domain for macro "LANGUAGE" To disable case-sensitivity.Extensions of Macro Support [JavaGen] MACRO=LANGUAGE=Java MACRO=ENVIRONMENT=GUI When the option is enabled. if there is no definition for a macro named TARGET_LANGUAGE. the value of the condition will be evaluated as FALSE. and the listing will contain the warning: 52954-W Case-insensitive comparison is true for macro “LANGUAGE” XXXXX-W Macro LANGUAGE was defined as “Java”.INI is already taken into account. the statement Set x := 2 will be left in the output file. you can use the macro in a rule.1. JAVA) Set x := 1 CG_ELSE Set x := 2 CG_ENDIF and the statement Set x := 1 will be left in the output file. When the option is not enabled. Macro Name Validation Even if a macro is not defined. the following statement will be evaluated as TRUE: CG_IF(LANGUAGE. German) Set PUSH_TEXT of SET_PUSH_MODE_I := 'Speichern' CG_ENDIF will not produce any code in the output file. If the option is enabled. comparison failed. This configuration option controls what is generated when a macro name cannot be validated. then the statement CG_IF(TARGET_LANGUAGE.1 Rules Language Reference Guide 12-15 . then rule preparation will fail with the following error message: AppBuilder 2. For example. use the following code generation parameter: -FMEXCI The following flag in HPS. Since the case of possible values of the LANGUAGE macro listed in the [MacroDomains] section of HPS. C [JavaGen] MACRO=LANGUAGE=Java MACRO=ENVIRONMENT=GUI [CGen] MACRO=LANGUAGE=C MACRO=ENVIRONMENT=GUI and case-sensitivity is disabled. For example.Only CG_IF is supported. use the following code generation parameter: -FMMBDEF The following flag in HPS. then the value used in the rule is validated against the values in the domain (the list of specified values with case-sensitivity defined using the Casesensitivity option). JAVA) Set x := 1 CG_ELSE Set x := 2 CG_ENDIF CG_IF(ENVIRONMENT. then rule prepare will fail with the following error message: 52960-S Value “French” is not listed in the domain for macro TARGET_LANGUAGE.Extensions of Macro Support 52965-S Macro "TARGET_LANGUAGE" is not defined. If the value is not in the domain. If the “MACRO_NAME” exists in this new section. then the following warning will be generated: 52825-W Undefined macro "TARGET_LANGUAGE". if HPS. This option works in the same way for macro definitions that have domains defined.INI can also be used: FLAG=MMBDEF Macro Value Validation A “[MacroDomains]” section has been added to HPS. the rule code contains: CG_IF(LANGUAGE.Cobol) Set z := 3 12-16 Macros . If this option is not enabled (default).INI. HTML) Set y := 1 CG_ELSE Set y := 2 CG_ENDIF CG_IF(LANGUAGE.INI contains: [MacroDomains] LANGUAGE=Java. To validate macro names. This file must contain allowable Rules Language statements and the File_name string format must be allowable on the platform where the rule is translated. but the “HTML” value will not be validated.Cobol) will result in preparation failure with the following error message: W52960-S Value “Cobol” is not listed in the domain for macro LANGUAGE CG_IFDEFINED/CG_IFNOTDEFINED Additional Notes Note that CG_IFDEFINED/CG_IFNOTDEFINED parameter (macro name) is expanded (as for all other commands) unless it is placed in CGMEX quotes (<: and :> by default).1. Including Files The CG_INCLUDE statement causes the compiler to process the file specified in the file_name parameter. as in the example: (CG_IFDEFINED(<:JAVA:>)). Macro INCLUDE Syntax CG_INCLUDE ( File_name ) where: File_name is the string specifying file name. In this example: CG_DEFINE(JAVA.Extensions of Macro Support CG_ENDIF The “JAVA” value will be validated against the values in the domain list. "Map 1 to I" is processed because <:JAVA:> is expanded into JAVA and this macro is defined. The statement: CG_IF(LANGUAGE. For example: CG_INCLUDE (e:\include\commonrulepart.inc) AppBuilder 2.1 Rules Language Reference Guide 12-17 . But if you were to place JAVA in quotes. TRUE) CG_IFDEFINED(JAVA) Map 1 to i CG_ELSE Map 0 to i CG_ENDIF "Map 0 to I" is processed because the CG_IFDEFINED parameter is expanded into TRUE but the macro named TRUE is not defined. For example. <::>. To help with creating loops. CG_SHIFT takes any number of parameters and returns the same list (each parameter quoted) after removing the first parameter. Example . . Note In order to break the process of translation.Extensions of Macro Support Exiting from Translation The CG_CGEXIT statement breaks the process of translation with the return code Return code.Exiting from translation CG_IFDEFINED(Cplusplus) Map 1 to i CG_ELSE CG_CGEXIT(8) *> this rule created for C++ only < * CG_ENDIF Using Recursion to Implement Loops Although macros do not directly support loops. This is a very complex procedure and it is recommended that you exercise caution to avoid creating endless loops. <:<:MAP 0 TO $1:> clear_all(CG_SHIFT($@)):>):>) clear_all( COUNTER. HEIGHT. there is a special macro statement: CG_SHIFT. consider the following macro that allows many variables to be set to 0 with one simple call: Macro use Result CG_DEFINE( clear_all. 12-18 Macros . <:CG_IFELSE( $1. Macro EXIT Syntax CG_CGEXIT ( Return code ) where: Return code is an integer number. you can simulate the effect of looping using recursion and conditionals. This macro uses recursion to process parameters one by one. the Return code value must not be less than the default error code (8). WIDTH) MAP 0 TO COUNTER MAP 0 TO HEIGHT MAP 0 TO WIDTH Using String Functions There are a number of predefined functions that manipulate strings in various ways: CG_LEN( string ) Returns the length of a string. <:DB2:>) CG_INDEX( <:DB2/2 database access:>. 5) access DB2/2 Using Arithmetic Macros Several macro statements support integer arithmetic. from . the macro returns everything to the end of the string. it is not possible to detect overflow situations and the result of any macro statements with an overflow is unpredictable. Macro use Result CG_INDEX( <:DB2/2 database access:>. Returns 0 if not found. length ) Extracts some part of a string starting at the FROM position. All calculations are performed using native C arithmetic which corresponds to CALCULATOR arithmetic with INTEGER type. <:Oracle:>) 1 0 CG_SUBSTR( string . if your expression contains division by zero. division by zero condition is handled. 1.1. the compile-time error is issued. 16) CG_SUBSTR( <:DB2/2 database access:>. Because native arithmetic is used.Extensions of Macro Support Macro use Result CG_LEN() CG_LEN( <:database:>) 0 8 CG_INDEX( string . it is the maximum size of the string returned. substring ) Returns the position of SUBSTRING in STRING. If LENGTH is not specified. Integer arithmetic with macros is done to 32-bit precision—the same as for integers in Rules Language. If LENGTH is specified. There are several ways to express numbers to allow various radixes to be specified. Macro use Result CG_SUBSTR( <:DB2/2 database access:>. The search is case-sensitive.1 Rules Language Reference Guide 12-19 . Table 12-2 Expressing numbers to allow various radixes to be specified Ways of expressing and indicated radixes No prefix indicates decimal A single 0 indicates octal 0x indicates hexadecimal 0b indicates binary 0r (where is a decimal number from 2 to 36) indicates a specific radix Example 22 49 78 23456 007 02 0123 0x1ff 0x55 0xabcd 0b1101 06:555 base 6 012:bbb duodecimal AppBuilder 2. Nevertheless. Returns 1 if found in the first position. See table Table 12-2. If the width is less than the length of the result. A width can be applied to make the result be 0 (zero). except exponentiation. A radix can be applied to work in bases other than 10 (the radix must be from 2 to 36 inclusive). Table 12-3 Operators Used in Expressions Operator Definition Unary minus Exponentiation ** * + << == ! ~ & ^ | && || / >> != > >= < <= % Multiplication. This macro statement takes any expression and replaces it with the result. are left associative. padded to at least the number of characters specified by the width parameter. (numbers count) then no truncation occurs.Extensions of Macro Support CG_INCR( number ) CG_DECR( number ) These macro statements increment or decrement an integer and return the result. 12-20 Macros . radix . as shown in Table 12-3 in decreasing order of precedence. 10) CG_INCR(amount) 30 13 11 CG_EVAL( expression . Macro use Result CG_INCR(29) CG_DECR(14) CG_DEFINE(amount. The expression can contain various operators. division and modulo Addition and subtraction Shift left or right Relational operators Logical negation Bitwise negation Bitwise and Bitwise exclusive-or Bitwise or Logical and Logical or All operators. width ) More complex mathematical operations are handled by CG_EVAL. Extensions of Macro Support Numbers can only be integers with 32-bit precision. There are several ways of expressing numbers to allow various radixes to be specified: • No prefix indicates decimal. For example: 22 49 78 23456 • A single 0 indicates octal. For example: 077 02 0123 • Ox indicates hexadecimal. For example: 0x1ff 0x55 0xabcd • 0b indicates binary. For example: 0b1101 • 0r : (where r is itself a number from 2 to 36) indicates a specific radix: 06:555 base 6 012:bbbb duodecimal To change precedence, use parentheses “(” and “)”. With relational operations, the value 1 is returned if it evaluates to True, otherwise the value is 0. Table 12-4 Macro Support Values Macro Use Result CG_EVAL(-2 * 5) CG_EVAL(CG_INDEX(Good day, 00) > 0) CG_DEFINE(cube, <:CG_EVAL(($1)**3):>) cube(4) -10 1 64 AppBuilder 2.1.1 Rules Language Reference Guide 12-21 Extensions of Macro Support 12-22 Macros CHAPTER 13 PLATFORM SUPPORT AND TARGET LANGUAGE SPECIFICS AppBuilder 2.1.1 Rules Language Reference Guide Using platform-specific Rules Language in AppBuilder, it is possible to translate a Rules Language application to C, Java, ClassicCOBOL, OpenCOBOL. Most of the Rules Language elements are supported for every target language, but there may be differences in syntax, semantics, and applicable functions. Complete descriptions of the Rules Language elements for each language can be found in the following sections: • Restrictions in C • Specific Considerations for C • Restrictions in Java • Specific Considerations for Java • Java Extensions • Restrictions in ClassicCOBOL • Specific Considerations for ClassicCOBOL • Restrictions in OpenCOBOL • Specific Considerations for OpenCOBOL Depending on the release and platform, there may be some differences in syntax, semantics, and applicable functions. For platform and release support tables, see Release Specific Considerations. AppBuilder 2.1.1 Rules Language Reference Guide 13-1 Restrictions in C Restrictions in C The following is a list of the restrictions in Rules Language for C. These restrictions apply to all AppBuilder releases. • Dynamic occurring views and support functions APPEND, DELETE, INSERT, REPLACE and RESIZE are not supported. • C generation is not DBCS certified. • DBCS and MIXED parameters with string functions are not supported. • CONVERSE REPORT statement is not supported. • ObjectSpeak support is deprecated. • In C development, you may only declare object aliases for the window objects. See “Aliases” for information on the Aliases object data item. • PRAGMA statement is restricted only to KEYWORD. • Set symbol decimal part is truncated if it is longer than declared in the set. • SETDISPLAY and SETENCODING accept only LOOKUP and ERROR sets as parameters. • SET statement with +:= or -:= is not supported. • +:= and -:= operators are not supported • The following functions are not supported: • ADDR(view) • CLEARNULL • ISNULL • GET_ROLLBACK_ONLY • SET_ROLLBACK_ONLY • LOC(...):OBJECT • INCR • DECR Specific Considerations for C The following sections describe the specific differences in Rules Language elements for C: • Variable for the Length of the VARCHAR Data Item in C • Comparing Views for C • Date and Time Functions in C • Common Procedures in C • Constructing an Event Handler in C • OVERLAY Statements in C 13-2 Platform Support and Target Language Specifics Specific Considerations for C Variable for the Length of the VARCHAR Data Item in C Changing the _LEN variable only effects the _LEN variable, the corresponding VARCHAR is not effected immediately. Therefore, any value is allowed for a _LEN variable, for example: MAP -1 TO VC_LEN MAP VC_LEN TO SomeVariable SomeVariable will contain –1. However, changing the _LEN variable effects how the string is interpreted in comparison and in some other constructions, for example: MAP "some string" TO VC MAP 0 TO VC_LEN IF VC = "" TRACE("VC is empty") ENDIF The trace statement will be executed because the length of the VC variable is set to zero; thus, VC becomes equal to ‘’(empty string). We do not recommend using the _LEN variable for write access (modifying the VARCHAR variable through its _LEN variable) in C mode. For more information refer to the following section: Variable for the Length of the VARCHAR Data Item. Comparing Views for C Comparison is implemented as a byte-by-byte memory comparison. If the views being compared are of unequal lengths, the shorter view is padded with blanks to equal the length of the longer view before the comparison is made. Because view comparison does not take into account the data type of the fields in the view, it is possible for the comparison of two views to give a different result than the comparison of the fields in the view. For more information, refer to the following section: Comparing Views. Object Method Call in C In C, Method can have optional parameters, which can be omitted when Method is called. For example: If A is the object of class CLS, B is the method of class CLS with three parameters where the second parameter is optional and C is the method of class CLS, which has three parameters where the third parameter is optional then the methods are used in the following way: A.B (D,, E) A.C (F,G,) Example of setting parameters for a C application DCL AppBuilder 2.1.1 Rules Language Reference Guide 13-3 Specific Considerations for C b object 'EXIT_BUTTON' ; i smallint; ENDDCL map b.IsEnabled to i *> This... <* map b.IsEnabled() to i *> ...and this call is equivalent <* Date and Time Functions in C If you omit the format string, the following default format string will be provided: • Format string specified by DFLTDTFMT setting of [CodeGenParameters] section of HPS.INI. • If HPS.INI settings are not specified, ISO formats are used: "%Y-%0m-%0d" for DATE and "%0t.%0m.%0s" for TIME. For more information, see “DATE and TIME” and “INI File Settings”. Common Procedures in C For C, you can use OBJECT POINTER, but OBJECT ARRAY and OBJECT cannot be used as procedure parameters. For more information refer to “Common Procedure Syntax” and “Procedure Syntax” . Constructing an Event Handler in C The following constructions cannot be used in the event handler body in C mode: • LOCAL PROCEDURE CALL • USE RULE • USE COMPONENT • CONVERSE WINDOW • RETURN OVERLAY Statements in C For more information on usage, refer to: • Using OVERLAY Statements with Character Data • Using OVERLAY Statements with Variable Data • Using OVERLAY Statements in Multiple-Occurring Views • Using OVERLAY Statements in a VARCHAR Data Item 13-4 Platform Support and Target Language Specifics If INDEX_CONTROL_ON is set to NO. Therefore. INDEX_CONTROL_ABORT setting is taken into account only if code was generated with INDEX_CONTROL_ON set to YES. and the application continues to execute. to the destination data item. INDEX_CONTROL_ABORT does not effect application behavior. the first occurrence is assumed. Example of Subscript Control in C Consider the following example. The default value is NO. assuming INDEX_CONTROL_ON=YES and INDEX_CONTROL_ABORT=NO: DCL I INTEGER. in any circumstance. If INDEX_CONTROL_ABORT is set to NO. Erroneous OVERLAY statements might not be noticed during compilation but can result in problems during execution. view subscript control code is generated and application behavior is controlled by INDEX_CONTROL_ABORT setting. and the value of HPSError is set to the corresponding error code. Note In this document.1. Subscript Control in C Subscript control of occurring views is performed in C mode.1 Rules Language Reference Guide 13-5 . If INDEX_CONTROL_ABORT is set to YES. Caution The OVERLAY statement can cause unexpected results. the first occurrence is assumed if subscript is out of range. Warning Data items of types MIXED and DBCS cannot. the application does not abort and the first occurrence is assumed if the subscript is out of range without any notification. ENDDCL AppBuilder 2. we urge you to use MAP statements (see caution note below) in all cases where OVERLAY statements are not necessary. and the default behavior is that is a “subscript is out of range” error occurs. For detailed information on error messages. be used in OVERLAY statements. see the Messages Reference Guide. See also “-I” code generation parameter. If you are using OVERLAY statements in your applications with data types that are not explicitly mentioned in this book. In the latter case.ini settings: INDEX_CONTROL_ON and INDEX_CONTROL_ABORT. the application does not abort. If INDEX_CONTROL_ON is set to YES (the default value). OVERLAY blindly copies all the source data item’s data. in its stored form. Although MAP carefully compares view structures to make sure that data ends up only in fields like those from which it came. for the statement OVERLAY var1 TO var2 var1 is the source and var2 is the destination. There is no guarantee that such applications can be ported to other platforms or supported from release to release. V(10) VIEW CONTAINS I. as a precautionary measure. the application aborts when a view subscript is out of range.Specific Considerations for C The OVERLAY statement can be used in AppBuilder to perform a byte-by-byte memory copy. both can have YES or NO values. Use caution when using OVERLAY. INDX INTEGER. It relies on two Hps. which bypasses the MAP statement safety mechanism. be aware that such applications are vulnerable to future failure. • CONVERSE and CONVERSE WINDOW statements are not supported. • The following functions are not supported: • HPSERROR • HPSResetError • HPSErrorMessage • LOC(view):CHAR • Escape sequences \a. 13-6 Platform Support and Target Language Specifics . \v. first occurrence assumed <* TRACE(I(1)) *> "2" is printed <* RETURN Restrictions in Java The following is a list of the restrictions in Rules Language for Java. first occurrence assumed <* TRACE(I(1)) *> "1" is printed <* IF HPSERROR = 6 TRACE("ERROR : Index out of bounds") *> This line is executed and * "ERROR : Index out of bounds" is printed <* ENDIF MAP 11 TO INDX MAP 2 TO I(INDX) *> Error: index greater than view size. I(10) is set to 1 <* -1 TO INDX 1 TO I(INDX) *> Error: index less than one. • Format strings are not supported in Java. • OVERLAY statement restriction: only VIEW can be used as a source and a target. • Decimal arithmetic COBOL and COMPATIBILITY modes are not supported.Restrictions in Java MAP MAP MAP MAP 10 TO INDX 1 TO I(INDX) *> Correct. • If set symbol is inconsistent with the set definition then the code generator will generate an error. These restrictions apply to all AppBuilder releases. \? are not supported. • There is no subscript control at compile time because of dynamic views support. refer to the following section: Data Types.util. It is the value of INTEGER variable. from Java components using the getJavaValue method of appbuilder.1. Each Rules data type has its representation as one of the Java data types. This representation can be obtained from external Java classes. For more information on data types. for example.1 Rules Language Reference Guide 13-7 .Specific Considerations for Java Specific Considerations for Java The following sections describe the specific differences in Rules Language elements for Java: • Java Values and Conversions • Variable for the Length of the VARCHAR Data Item in Java • OBJECT and OBJECT POINTER in Java • Comparing Views for Java • ObjectSpeak Conversions • Functions in Java • Local Procedure Declaration in Java • Event Procedure Declaration in Java • Defining Views in Java • Constructing an Event Handler in Java • SQL ASIS Support in Java • Transaction Support in Java Java Values and Conversions This section contains special considerations for using data types in Java.*classes. The following Rules Language data types are described in this section: • INTEGER • SMALLINT • DEC and PIC • CHAR and VARCHAR • Variable for the Length of the VARCHAR Data Item in Java • DATE and TIME in Java • TIMESTAMP • BOOLEAN • TEXT and IMAGE • OBJECT and OBJECT POINTER in Java INTEGER Java value has type INT. AppBuilder 2. the maximum length is assumed.lang. It is the value of the CHAR or VARCHAR variable. 13-8 Platform Support and Target Language Specifics .math. It is the value of PIC or DEC variable. It is the value of SMALLINT variable. If _LEN is assigned a negative value. Variable for the Length of the VARCHAR Data Item in Java Changing the _LEN variable immediately changes the corresponding VARCHAR data. VARCHAR(20). CHAR and VARCHAR Java value has type java.Specific Considerations for Java SMALLINT Java value has type short.String. zero length is assumed.BigDecimal. For more information refer to the following section: Variable for the Length of the VARCHAR Data Item. DEC and PIC Java value has type java. Example 2 DCL VC1 VC2 VARCHAR(10). ENDDCL MAP "12345" TO VC1 MAP 10 TO VC1_LEN MAP VC1 TO VC2 MAP VC2 ++ "A" TO VC2 VC2 will contain ‘12345 A’ (five spaces before A). Examples Example 1: MAP -1 TO VC_LEN TRACE(VC_LEN) // 0 will be printed You can safely modify the _LEN field of VARCHAR without restrictions. If _LEN is assigned more than the VARCHAR maximum length. This data type represents a non-typed reference to an object.util.String.lang. It is the value of the BOOLEAN variable. 1999 03:00:00 GMT on the computer running in St. when TIMESTAMP is converted to a Java value. DATE and TIME in Java Java value has type java. Russia is in the GMT +03:00 time zone. USA is in the GMT –05:00 time zone.1.Date. 1999 is java. Since any object (object of any class) could be mapped to OBJECT data type.lang. as explained in the DATE and TIME in Java data type section. each character (whether double. it is useful when you want to perform a type conversion.Specific Considerations for Java DBCS and MIXED Data Types in Java Java value has type java.util.Object. The Java value of the DATE variable representing June 03. therefore.00 of the date value in the DATE variable in the local time zone. Petersburg and June 02. Note that java. Keep the following in mind when writing Java applications: A MIXED data item’s length is calculated in characters in Java and can have a maximum length of 32K.Date is the time value in the TIME variable at January 1st.lang.Date.lang. Petersburg. St. Java value is java. a varied number of characters can fit into a particular MIXED field. 1999 19:00:00 GMT on the computer running in Cary. 1970 (Java “epoch” date) in the local time zone. In Java. any fraction is lost. TIMESTAMP Java value has type java. DBCS characters are converted to Unicode (java. NC.00. The Java value type java. Because of the differences in character representation on different platforms. TEXT and IMAGE Java value has type java.util. Java values of the equal TIME variable are different in different time zones. It is 00. OBJECT and OBJECT POINTER in Java In Java.or single-byte) occupies one position in a MIXED string For more information on the DBCS and MIXED data types refer to the following section: “DBCS and MIXED Data Types”.1 Rules Language Reference Guide 13-9 . AppBuilder 2. Trailing blanks are trimmed.lang. which corresponds to June 03. It is the moment of time contained in the TIMESTAMP variable in local time.String).Date does not support fractions. Java values of the equal DATE variables are different in different time zones.util. It is the value of the DBCS or MIXED variable. It is the value of TEXT or IMAGE field (file name). For example: Cary. It is an object referenced by the OBJECT variable. OBJECT data type is equivalent to OBJECT POINTER data type. BOOLEAN Java value has type boolean.String.Date. Specific Considerations for Java Using Object Data Types for Java New objects created using the form OBJECT TYPE can only be used in Java application development. java_button2 OBJECT TYPE ‘java. ENDDCL MAP radio TO obj MAP push TO obj Example 2 Using OBJECT For Conversion in Java DCL obj OBJECT.awt. resizeComponent PROC (comp OBJECT TYPE 'javax.Button’ ).swing.JComponent'). radio OBJECT TYPE RadioButton OF GUI_KERNEL. button_proc PROC ( btn OBJECT TYPE ‘java. you may only declare object aliases for the window objects. Note In C development. See “Aliases” for information on the Aliases object data item.Button and a local procedure with a parameter of the same type. ENDDCL resizeComponent(radio) *>Illegal: type of object "radio" is incompatible with type of procedure formal parameter <* MAP radio TO obj resizeComponent(obj) *>Valid: since obj has type OBJECT and this type represents non-typed reference<* New objects created using the form OBJECT TYPE can only be used in Java application development. radio OBJECT TYPE RadioButton OF GUI_KERNEL. ENDDCL This declares objects of type java.awt. Example 1 Using OBJECT Data Type in Java DCL obj OBJECT. you may only declare object aliases for the window objects. Declaration of OBJECT TYPE is equivalent to the OBJECT POINTER declaration. Example 3 OBJECT Declaration DCL java_button1 OBJECT TYPE ‘java.awt.Using OBJECT in Java The following are examples of different ways to use OBJECT in Java.Button’.Button’ OF JAVABEANS. See “Aliases” for information on the Aliases object data item. 13-10 Platform Support and Target Language Specifics . push OBJECT POINTER TO PushButton OF GUI_KERNEL.awt. Note In C development. Examples . ENDDCL MAP push1 TO mybutton where push1 is the system identifier (HPS ID) or alias of a push button on a window that the rule converses. Use a MAP statement to assign a value to an object pointer. Examples using Object Pointer Example 1 . Use OBJECT POINTER TO to declare a pointer to an object. and set its foreground color. enableField( field01 ) AppBuilder 2. .200. For more information on the Object data types refer to the following section: “OBJECT and OBJECT POINTER”. Note Method names and types in this example correspond to a C Language application. you write a procedure that deals with any object of a particular type. For example. that this data type’s use is discouraged. OBJECT POINTER TO represents a reference to an object of particular type.Object Pointer Declaration DCL mybutton OBJECT POINTER TO PushButton. Be aware. By declaring a pointer as a parameter. To invoke the procedure.ForeColor(RGB(175.90)) ENDPROC . pass it the name of a particular edit field: PROC enableField (myField OBJECT POINTER TO EditField) MyField.Enabled(1) myField.Object Pointer as Parameter An object pointer is particularly useful as a parameter to a common procedure. OBJECT POINTER data type is still supported in Rules Language.Visible(1) myField. Object pointers are initialized with a NULL value. OBJECT POINTER data type is equivalent to OBJECT data type.1 Rules Language Reference Guide 13-11 .Specific Considerations for Java Using Object Pointer in Java Caution For backward compatibility with AppBuilder 5. Example 2 . you might write the following procedure to enable an edit field.0.4.1. however. make it visible. 13-12 Platform Support and Target Language Specifics . If one view has more fields than another.Object Pointer in Event Procedure Events often include parameters. You use an object pointer in an event procedure (see “Event Handling Procedure”) to represent a parameter of type POINTER or OBJECT received from an event triggered by a control.Specific Considerations for Java Example 3 . ENDDCL PROC Button1Click For Click OBJECT b (p OBJECT TYPE ClickEvent) map b.and this call is equivalent <* ENDPROC Creating a New Object Instance for Java The following is an example of creating a new object instance in Java. Str VARCHAR(50).. you might code the following procedure to handle Initialize events from your rule window. If you try to compare views with different structures. For more information. • MY_WINDOW is the system identifier of the rule's window. • InitializeEvent is the type of object to which a parameter points. • p is the name (in the procedure) of the parameter received with the Initialize event from MY_WINDOW.. For example. • Initialize is the type of event handled. refer to the following section: Comparing Views. Views are compared field by field recursively. it is considered greater than the latter views (if all the rest of the fields are equal).Text() to Str *> . Object Method Call in Java The following is an example of setting parameters for a Java application. In this example. an exception is thrown at runtime. PROC InitWindow FOR Initialize OBJECT MY_WINDOW (p OBJECT TYPE InitializeEvent) ENDPROC In this procedure: • InitWindow is the procedure name.Text to Str *> This. views that could be converted to each other. Example of setting parameters for a Java application DCL b object 'EXIT_BUTTON' . <* map b... the parameter passed by the window is a pointer to an object of type InitializeEvent. that is. Comparing Views for Java Comparison is implemented for convertible views. lang. the nearest representable value is used.1.String can be converted to the value of type CHAR. INTEGER.awt. p OBJECT TYPE ’java.awt. DBCS. and vice versa. float. 0.Setting Object Constructor Parameters DCL label VARCHAR(200). AppBuilder 2. Numeric Type Any Java value of type char. When converting from DEC or PIC to INTEGER. For example.1 Rules Language Reference Guide 13-13 . or double can be converted to the value of any of the following types: SMALLINT. Note Refer to the ObjectSpeak Reference Guide for more information about ObjectSpeak. For SMALLINT and INTEGER. if the integer value does not fit into the integer part. String Type Java value of type java.Button’(’label’)) TO label For additional information see Creating a New Object Instance ObjectSpeak Conversions This topic describes conversions performed between Java standard data types and Rules types when passing parameters to and accepting return values from Java methods. When converting from integers to DEC or PIC. If the value is too large. The overflowed value is converted to zero (0).getLabel()) ENDPROC MAP CreateButton TO p MAP NEW ’java. long.Button’. conversion is straight forward. the fraction part is truncated. or MIXED.1 cannot be represented exactly in float or double type. ENDDCL PROC CreateButton : LIKE p PROC RETURN (NEW ’java. When converting from DEC or PIC to floats.Button’) ENDPROC PROC GetLabel(btn LIKE p) : VARCHAR(200) PROC RETURN (btn. If the integer part does not fit into the integer type.Button’(’label’) TO p MAP GetLabel(NEW ’java. byte. DEC. int. or PIC. the assigned value is unpredictable. and vice versa.Specific Considerations for Java Example . the overflowed value is truncated. it is truncated.awt.awt. short. VARCHAR. util. and vice versa. and TIMESTAMP.INI setting is not specified. 13-14 Platform Support and Target Language Specifics . Boolean Type Java values of boolean type can be converted to type BOOLEAN. Date and Time Type Java values of type java. • If APPBUILDER. all classes in Java and OBJECT data types are mutually convertible to Java subclassing rules. and vice versa. see “DATE and TIME”. without any conversion. For more information. Functions in Java The following functions have specific considerations for Java: • Date and Time Functions in Java • RTRIM in Java • UPPER and LOWER in Java • STRLEN in Java • VERIFY in Java • SUBSTR in Java • CHAR in Java • Double-Byte Character Set Functions in Java • LOC in Java • TRACE in Java Date and Time Functions in Java If you omit the format string.INI.INI setting is not specified. then the parameter is considered to be the correct value of the TIME data type and is used as is. the default system value (Java regional setting) is used for Date.Date can be converted to types DATE.Specific Considerations for Java OBJECT Type In Rules. • If APPBUILDER. Rules of conversion are the same as described in “Java Values and Conversions”. the following default format string will be provided: • Format string specified by DEFAULT_DATE_FORMAT or DEFAULT_TIME_FORMAT settings of [NC] section of APPBUILDER. TIME. UPPER and LOWER in Java Characters are converted to upper and lower case according to the specified codepage. When STRLEN is applied to MIXED string. For more information see“VERIFY”. meaning a variable which was initialized with a NULL value and never changed. these conversion functions just change the types of their arguments and perform validation as explained in “Validation and Implementation”. if the CHAR function is applied to an uninitialized numeric variable. the function returns the same invalid string with trailing DBCS blanks removed. the function parameter is not required to be a valid MIXED string. Double-Byte Character Set Functions in Java In Java. MIXED or DBCS parameters can contain invalid characters. For more information see“RTRIM”. this codepage is the current system codepage. if RTRIM is applied to an invalid DBCS string. For more information see“CHAR”. In Java. AppBuilder 2.1 Rules Language Reference Guide 13-15 . the function parameter is not required to be a valid DBCS string. For more information see“STRLEN”. an exception is raised at runtime.ini file. otherwise. SUBSTR in Java In Java. CHAR in Java In Java. For more information see“SUBSTR”. For more information see“UPPER and LOWER” and “UPPER and LOWER”.Specific Considerations for Java RTRIM in Java In Java. codepage validation is specified by the DBCS_VALIDATION_CODEPAGE parameter in the [VALIDATION] section of the appbuilder.1. In Java. VERIFY in Java In Java.ini file. then CHAR will return a string containing the zero symbol. If this setting is TRUE. MIXED or DBCS parameters can contain invalid characters. an empty string is returned. then the value returned depends on the SHOW_ZERO_ON_NULL setting in the appbuilder. This ini setting can be changed without recompilation. STRLEN in Java In Java when STRLEN is applied to a DBCS string. If validation fails. Untyped OBJECT is returned.AbfDataObject descendant. see the ObjectSpeak Reference Guide.put(LOC(Key). Event Procedure Declaration in Java For more information refer to “Event Procedure Syntax”.util. Example .Using LOC Function in Java Mode This function can be used to pass references to data items in a rule to Java classes.In Java. 13-16 Platform Support and Target Language Specifics . LOC returns an object representing a given data field. V VIEW CONTAINS I.util.ini is set to 1 or greater. For more information refer to “TRACE”.util. DCL I INTEGER. Local Procedure Declaration in Java For Java.lang.HashMap' TO MyMap MyMap. LOC returns Rules OBJECT represented by Java class 'appbuilder. Every data field in a rule is represented in Java by an instance ofappbuilder. Value) *> Illegal. Key VARCHAR(20).util. ENDDCL MAP LOC(I) TO O MAP LOC(V) TO O MAP NEW 'java. trace is output only if the APP_LEVEL setting in the [TRACE] section of appbuilder. any data type can be used as a procedure parameter. MyMap OBJECT TYPE 'java. For more information refer to “LOC”. O OBJECT. LOC(Value)) *> Legal parameter types are java.Specific Considerations for Java LOC in Java In Java. LOC may accept not only views but also fields as arguments.put(Key.HashMap'. wrong parameter types <* MyMap. For more information refer to “Local Procedure Syntax”. Value VARCHAR(255).Object<* TRACE in Java In Java. For a detailed list of supported events.AbfDataObject' referencing a given field or view. hand3 proc for keyPressed type ‘java.event. w. see “Assignment Statements”).awt. ButtonPtr object ‘java. Although the first definition has no LISTENER clause. it is equivalent to the second definition.KeyEvent’ ). two handlers. Example .awt.event.1.Button’ ( evt object ‘java. are declared for the event keyPressed for objects of type java. Defining Views in Java In Java. using the LISTENER clause produces the same result. For a description of the view mapping algorithm. hand2 proc for keyTyped listener ‘java.event. In both cases.awt. ENDDCL In this example.awt.Button.KeyListener’ type ‘java.awt. you can define a local procedure that has one or more parameters of view type without defining the view type more precisely. view mapping is performed dynamically during execution according to the view mapping algorithm. j.awt.awt.event.1 Rules Language Reference Guide 13-17 .KeyEvent’. This handler declaration is equivalent to the previous two. j integer.awt. ENDDCL The event handlers HandlerForPointer and HandlerForObject are declared for the distinct object referenced respectively by the variables ButtonPtr and Button.awt. HandlerForPointer proc for keyPressed object ButtonPtr ( evt like event ). hand1 and hand2.Button’. w view contains i. button object type ‘java. z view contains u. u view contains i. In these cases.Specific Considerations for Java Example . HandlerForObject proc for keyPressed object button ( evt like event ). ENDDCL PROC p ( v view ) MAP v to u ENDPROC AppBuilder 2.Button’.Button’ (evt object ‘java.KeyEvent’ ).awt. A non-typed view can only be used in its entirety in a MAP statement or when passing as a parameter to another procedure.Button’ ( evt object ‘java.View Mapping DCL i.event.KeyEvent’ ).Java LISTENER Clause DCL hand1 proc for keyPressed type ‘java. This procedure call can get any view as an actual parameter.awt. DCL event object ‘java. but not all errors are reported. The following restrictions apply: • Dynamic SQL is not supported. • Indicator variables only indicate that an associated host variable has a NULL value. No other error are indicated. except the RETURN statement. You can also use ISNULL to test for a NULL value in a field along with the PROPAGATE_NULL_TO_DATABASE=TRUE in the appbuilder. SQL ASIS Support in Java Java does not support embedded SQL. This allows more flexible DBMS support. All the Rules Language constructions. can be used in the event handler body in Java.Specific Considerations for Java p(w) *> Here i of w is assigned to i of u <* p(z) *> No assignments is performed – i is on different level in z <* p(u) *> i of u assigned to i of u <* Constructing an Event Handler in Java The following constructions can be used in the event handler body in Java mode: • Local procedure call • USE RULE • USE COMPONENT • CONVERSE WINDOW Note RETURN cannot be used in the event handler in Java application development. AppBuilder generates SQLJ from the code in SQL ASIS. it supports SQLJ.ini file. An error may be generated if a dynamic SQL statement is found in SQL ASIS code. cursor is generated FOR UPDATE except in the following cases which generate the cursor implicitly READ ONLY: • the outer fullselect includes a GROUP BY clause or HAVING clause • the outer fullselect includes column functions in the select list • the outer fullselect includes UNION or UNION ALL • the select-clause of the outer fullselect includes DISTINCT • the select-statement includes an ORDER BY clause • the select-statement includes a READ ONLY clause 13-18 Platform Support and Target Language Specifics . • By default. This is because NULL values are supported for Java. an error is issued at preparation time. See PRAGMA SQLCURSOR for Java. time. otherwise.. Using Host Variables in SQL Code In Java. Examples using Host Variables in SQL Code PRAGMA SQLCURSOR (myCursor.. You cannot use a host expression more complex than a single variable.. varchar(10)) DCL myDate date.. even with the same list of field types.. because a cursor must be declared in the same rule where it is used. or if the PRAGMA SQLCURSOR is after FETCH from this cursor.. Cursor field types are defined by types of textual first FETCH target variables or by the PRAGMA SQLCURSOR clause. cursor field types are defined by the first FETCH and a warning is generated on other FETCHes with different target variables types.INTO) • All other SQL statements must have syntax that is accepted by the Java SQLJ preprocessor for the installed database. This enables correct host vars conversion to be generated at the correct place.. Host variables that were used in DECLARE . an error will be issued.1: • Declare cursor statement (DECLARE. then PRAGMA SQLCURSOR must be used in the rule. date.CURSOR) • Open statement (OPEN. You can use a host variable even if its name is equal to a SQL reserved word without enclosing it in quotes. If cursor fields types are different in the FETCH statement and the PRAGMA SQLCURSOR and the PRAGMA preceded FETCH. Version 1. OPEN.... CLOSE and FETCH). • It is possible to use delimited identifiers (identifiers enclosed in double-quotes) anywhere where an ordinary identifier is allowed except for host variable name and cursor name. If there is more than one PRAGMA SQLCURSOR for the same cursor. • Host expressions can only use host variables.Specific Considerations for Java • the select-statement includes a FETCH FIRST n ROWS ONLY clause The above fullselects and select-clauses refer to DECLARE CURSOR statements only. • Cursors must be declared with DECLARE CURSOR before the first use. the same warnings are generated. Cursor name must not coincide with any SQL reserved word. ENDDCL SQL ASIS AppBuilder 2.. For additional information see File Access Statements. • If there no FETCH statements in the rule and all the required table columns are not listed.. • SQL ASIS block cannot contain stored procedure declaration.) • Close statement (CLOSE.1. • It is not possible to use a cursor returned from stored procedure. CURSOR. • The syntax for the following constructs must comply with IBM R DB2 Universal Database SQL Reference for Cross Platform Development.1 Rules Language Reference Guide 13-19 . If there are several FETCHes from the same cursor but types of their corresponding host variables are different. CURSOR statements are converted before and after SQL ASIS block containing OPEN statement for the cursor.) • Fetch statement (FETCH. SQL constructs concerning cursors are analyzed (DECLARE . Transaction Support in Java In Java.. fMydate)%*/. fMydate)%*/. an enterprise Java bean (EJB) for a bean-managed transaction. value of myDate variable that is used in DECLARE myCursor CURSOR statement is taken at the time of OPEN myCursor execution.map( AbfDate. For details.Specific Considerations for Java Declare myCursor cursor for Select Column1. HTML. /*%ConverseOut(RSQL_DATE. or a Java client. COLUMN2 FROM MYTABLE WHERE COLUMN3 = :V_TMP_SQL_1 } . #sql [dbContext] crsMycursor = { SELECT COLUMN1. CURSOR. V_TMP_SQL_1. and EJB.getCurrentDate() ). // 0018: SQL ASIS /*%ConverseIn(RSQL_DATE. the Rules Language provides support for transaction management with these statements: • START TRANSACTION • COMMIT TRANSACTION • ROLLBACK TRANSACTION With the Development Kit for Java. V_TMP_SQL_1. Thus.. you can use these statements with a servlet. Column2 From myTable Where Column3 = :myDate ENDSQL set myDate := date () SQL ASIS open myCursor ENDSQL This results in the following which has been simplified for clarity: // 0016: set myDate := date () fMydate. read these topics: • EJB (Container to Bean) Transactions • Client and Servlet Transaction • Closing Semantics and Rollback • Clients and Database Connection Pool 13-20 Platform Support and Target Language Specifics . not at DECLARE . For example: [DB] INITIAL_CONTEXT_FACTORY=java_class_name PROVIDER_URL=protocol://host_name:port_number These are the same parameters used for an initial context in the application server. you should not use any of the transaction statements from the Rules Language because transactions are managed by the application server and the container. <ejb-jar> <enterprise-beans> <session> ……. For normal use. Java bean-managed transactions also use transaction statements. Client and Servlet Transaction AppBuilder also supports client-managed transactions. <transaction-type>Bean</transaction-type> </session> ………. Closing Semantics and Rollback Use transaction statements to handle rollbacks. • Do not converse any window between start and commit/rollback statements.Specific Considerations for Java EJB (Container to Bean) Transactions AppBuilder generates container-managed EJBs.. • Do not use detached rules. You can check the rollback status by using the GET_ROLLBACK_ONLY function. We do not recommend using the SQL ASIS statement to manage transactions because the application server cannot handle the transaction context. There are also restrictions for a full Java client. It prohibits your transactions from being propagated and possibly even processed correctly. You also need to provide information about the transaction context in the appbuilder.ini file. Container-managed transactions automatically handle rollbacks by means of the rollback flag using the SET_ROLLBACK_ONLY function. This is the preferred mode of transaction support. For increased flexibility. Use this mode very carefully because transaction context in this case exists for a longer period of time and can potentially induce deadlocks. It returns TRUE if the SET_ROLLBACK_ONLY function is called.xml from Container to Bean. • Set SEPARATE_RPC_THREAD=FALSE in the appbuilder.1 Rules Language Reference Guide 13-21 . commit. AppBuilder 2. we recommend bean-managed transactions. You should modify the transaction type in the file ejb-jar.ini file. </ejb-jar> You should take care of transactions themselves by using Rules Language statements to start. it returns FALSE. and rollback transactions.1. otherwise. • Set the DBACCESS parameter to a value of APPSERVER in the [DB] section of the appbuilder. For additional information see“File Access Statements”. This setting allows you to set whether or not to abort (terminate) an application when a view subscript is out of range. I(10) is set to 1 <* -1 TO INDX 1 TO I(INDX) *> Error: index less than one.Specific Considerations for Java Clients and Database Connection Pool Users can take advantage of resource management of the database connection from the application server. It relies on the INDEX_CONTROL_ABORT setting of appbuilder. first occurrence assumed <* TRACE(I(1)) *> "1" is printed <* MAP 11 TO INDX MAP 2 TO I(INDX) *> Error: index greater than view size. an exception is thrown and the application terminates. first occurrence assumed <* TRACE(I(1)) *> "2" is printed <* RETURN 13-22 Platform Support and Target Language Specifics . Possible values of INDEX_CONTROL_ABORT setting are TRUE or FALSE. V(10) VIEW CONTAINS I. • Set the INITIAL_CONTEXT_FACTORY and the PROVIDER_URL parameters in the [DB] section of the appbuilder.ini.ini file. If set to FALSE. Subscript Control in Java Subscript control of occurring views is performed in Java mode. INDX INTEGER.ini file. Example of Subscript Control in Java Consider the following example. assuming INDEX_CONTROL_ABORT=FALSE: DCL I INTEGER. They can use the database connection pool on the client side by doing the following. The default behavior is that if a “subscript is out of range” error occurs. Default value is TRUE. • Set the implementation name of the database object to the database connection pool name. then no exception is thrown and the first occurrence is assumed if subscript is out of range. ENDDCL MAP MAP MAP MAP 10 TO INDX 1 TO I(INDX) *> Correct. AppBuilder 2.. DETACH OBJECT Statement in Java • CONVERSE REPORT Statements in Java Data Items in Java See the following for specific considerations when using data items in Java: • Initialization • NULL • Default Object Initialization All variables are initialized with NULL in Java mode (see NULL description). an initial value which corresponds to the variable type is assumed. This function sets a variable value to NULL in Java just as the internal initialization routines does.1 Rules Language Reference Guide 13-23 . For example. if a NULL BOOLEAN variable is used as an IF condition. if a variable with a NULL value is used in a Rules Language expression where its particular value is required.. However. a FALSE value is assumed.1. You can reset a variable value to its initial value using the CLEAR function (see CLEAR Statement in Assignment Statements).Java Extensions Java Extensions The following sections describe the extensions to the Rules Language available for Java: • Data Items in Java • Additional Functions for Java • Dynamically-Set View Functions • PRAGMA CLASSIMPORT for Java • PRAGMA CLASSIMPORT for Java • Setting Number of Occurrences (Right-Side Subscript) • PRAGMA CLASSIMPORT for Java • PRAGMA AUTOHANDLERS for Java • PRAGMA ALIAS PROPERTY for Java • PRAGMA COMMONHANDLER for Java • Static and Static Final Methods and Variables in Java • Event Handler Statement in Java • OVERLAY Statements in Java • Assigning Object Data Type Variables in Java • CASEOF in Java • USE RULE . and additionally. of type OBJECT TYPE Rule . a FALSE value is assumed. For example. If a variable has a NULL value it means that this variable was never assigned a value. If the system identifier is not a valid Rules Language identifier. initialized to an instance of a set with this long name. it can be used if the window long name is the same as rule long name. However. For more information. • Variable <Window long name>. the following variables can be accessed in a rule without declaring them in the DCL section. refer to the following section: Initialization. if a variable with NULL value is used in a Rules Language expression where its particular value is required. “Using Entities with Equal Names” for more details on the naming restrictions. each of its respective type initialized to an instance of the respective object. refer to the following section: Object Data Items. and ISNULL functions allow you to manage the NULL attribute. Note See Data Items. if NULL BOOLEAN variable is used as an IF condition. Additional Functions for Java The following functions are only available in Java: • CLEARNULL • ISNULL CLEARNULL This is available for Java only. of type OBJECT TYPE Rule has the same meaning as the previous variable (<Rule long name>). of type OBJECT TYPE Window . 13-24 Platform Support and Target Language Specifics .initialized to an instance of the executing rule. there is a special value for variables of all data types named NULL (introduced for database compatibility). For more information. can still be used in a rule by creating an alias for it (variable of type OBJECT 'HPSID'). CLEARNULL. however. If the window long name is the same as the rule long name.Java Extensions NULL In Java development. • Variables with names equal to the system identifiers of window objects. this variable is not created. The ISCLEAR Operator. • Variable <Set long name> of type OBJECT TYPE Set. an initial value corresponding to variable type is assumed.initialized to an instance of a window conversed by rule • Variable <Rule long name>. Default Object In Java. • Variable ThisRule. a variable for it is not created. NULL indicates "no value". See ObjectSpeak Reference for a description of Set object and dynamic set behavior. This system identifier. ISNULL returns FALSE). (See “Object Data Types”.) If you wish to test a variable of any object type (“Object Data Types”) for null. B BOOLEAN. ENDDCL CLEARNULL(I) *>I is set to its initial value . After this function invocation. ISNULL returns TRUE. INTEGER. The ISNULL function takes a field as an argument and returns a BOOLEAN value indicating whether the field is NULL or not. Examples of ISNULL and null and cleared fields Example Using ISNULL Function DCL CH I B OBJ V ENDDCL CHAR.zero<* MAP ISNULL(I) TO B *>B is FALSE<* MAP ISCLEAR(I) TO B *>B is TRUE.1 Rules Language Reference Guide 13-25 . BOOLEAN. If the field’s value is NULL.Using CLEARNULL Function DCL I INTEGER. it is not NULL any longer (that is. A field is considered to be set to NULL if it has never been modified by a user or if it has been reset programmatically by using the CLEAR statement. otherwise it returns FALSE.1. Example . For example. if you assign a value of 0 to an integer field. This is not the same as the field initial value. the field contains its initial value. MAP ISNULL(I + 1) TO B *>Compile time error: ISNULL cannot be applied to expression<* AppBuilder 2. as if the field has not changed. ISCLEAR being applied to this field returns TRUE. use ISCLEAR. Note The ISNULL support function cannot be applied to variables of any object type.Java Extensions The CLEARNULL function takes a field or a view as an argument and clears the NULL attribute of the field or every view's field if it is applied to a view. it will return TRUE if this reference actually refers to nothing. In other words. Note The CLEARNULL support function cannot be applied to variables of any object type. OBJECT TYPE Rule. because I contains its initial value<* RETURN ISNULL This is available for Java only. it contains a null value and returns FALSE if it refers to some object (non-NULL value). however. VIEW CONTAINS CH. Java Extensions MAP ISNULL(OBJ) TO B *>Compile time error: ISNULL cannot be applied to object<* MAP ISNULL(V) TO B *>Compile time error: ISNULL cannot be applied to view<* MAP ISNULL(CH) TO B *>Since all fields upon rule start are initialized with NULL value. because I was modified<* is TRUE. because I contains initial value<* RETURN SET_ROLLBACK_ONLY This is available for Java only. REPLACE and APPEND functions with the "number of occurs to process" parameter are supported. The SET_ROLLBACK_ONLY function modifies the transaction associated with the current thread so that the only possible outcome of the transaction is to roll back the transaction. indicating whether the only possible outcome of the transaction associated with the current thread is to roll back the transaction (TRUE) or not (FALSE). that is. zero<* is FALSE. Note This function has no parameters. B BOOLEAN. Dynamically-Set View Functions Note INSERT. The GET_ROLLBACK_ONLY function returns a BOOLEAN value. 13-26 Platform Support and Target Language Specifics . since B was assigned TRUE <* RETURN Example Using Null and Cleared Fields The following example illustrates the differences between null and cleared fields: DCL I INTEGER. B is TRUE <* MAP ISNULL(I) TO B *>B is TRUE <* MAP ISNULL(B) TO B *>B is FALSE. ENDDCL MAP MAP MAP MAP MAP ISNULL(I) ISCLEAR(I) 0 ISNULL(I) ISCLEAR(I) TO TO TO TO TO B B I B B *>B *>B *>I *>B *>B its is TRUE<* is TRUE<* contains initial value. GET_ROLLBACK_ONLY This is available for Java only. from position . source view . new size . V2. V VIEW CONTAINS V1(10).J. it returns 0. source view ( target view ) . number_of_occurs_to_process ) REPLACE ( target view . number ) INSERT ( target view .1 Rules Language Reference Guide 13-27 .1. from position . from position ) DELETE ( target view . from position . For non-occurring views. number_of_occurs_to_process ) OCCURS This function returns the number of occurrences of a given view.. you can change the number of occurrences in views dynamically while a rule executes using the standard functions: • APPEND • RESIZE • INSERT • REPLACE • DELETE Dynamically-Set View Syntax OCCURS APPEND ( view ) .Using OCCURS Function DCL I. V2 VIEW CONTAINS J. COUNT INTEGER. V3 VIEW CONTAINS I. J INTEGER.Java Extensions In Java. V3(1). though with 1 occurrence only <* MAP OCCURS(V1(1)) TO COUNT *> 0 – not an occurring view <* AppBuilder 2. ENDDCL MAP OCCURS(V1) TO COUNT *> 10 <* MAP OCCURS(V2) TO COUNT *> 0 – V2 is not an occurring view <* MAP OCCURS(V3) TO COUNT *> 1 – V3 is an occurring view. number_of_occurs_to_process RESIZE ( target view . Note This function is also available in C mode. Example . V1 VIEW CONTAINS I. source view . Views must be identical in structure. The target_view must be an occurring view but source_view can be any view. all occurrences are lost. no items from source_view will be taken (zero is assumed). V4) TRACE (I of V1(25)) *>Outputs: “4” <* APPEND(V1. By default. V VIEW CONTAINS V1(10). If it is less than zero. V1.Java Extensions APPEND Appends source_view to target_view. The first argument is the view and the second argument is the new size. C.Using APPEND Function DCL I INTEGER. Example . If a third argument is specified. it keeps as many occurrences as possible starting from a specified position. V2(14). RESIZE behaves as if from_position is not given. all items from it will be used and a warning will be issued at runtime. I OF V1(11)) *> Outputs: “1 2” <* APPEND (V1. it keeps as many occurrences as possible starting from the beginning of the view. Occurrences between the first position and from_position are then lost. Example . V4(10). V3. V4 VIEW CONTAINS I. If it is greater than the size of source_view. OF V1(1) OF V2(1) OF V4(1) V2) MAP OCCURS(V1) TO COUNT TRACE(COUNT) *> Outputs: "24" <* TRACE(I OF V1(1). If from_position is less or equal to zero.Using RESIZE Function 13-28 Platform Support and Target Language Specifics . ENDDCL MAP 1 TO I MAP 2 TO I MAP 4 TO I APPEND(V1. W) *> Illegal: views of different structure <* APPEND(V3. V3. If from_position is greater than the upper bound. W VIEW CONTAINS I. The "number of occurs to process" parameter specifies how many items should be taken from source_view. V2. C CHAR(10). V1) *> Illegal: V3 is not an occurring view <* RESIZE Resizes (shrinks or expands) the given occurring view to a new size. Java Extensions DCL I. 2. all items from it will be used and a warning will be issued at runtime. only one the view <* INSERT Inserts all occurrences of the source view (or the view itself if it is the plain view) at the specified position in the target view. C CHAR(10). V3 VIEW CONTAINS I. it deletes as many as possible until the end of the view.1. If it is less than zero. starting from the position given in the second argument. it deletes number occurrences starting from the given position.1 Rules Language Reference Guide 13-29 . 5) *> occurrences 1 through DELETE(V. 1) *> occurrences remaining DELETE(V. 10) *> occurrence is left in Deletes occurrences 5 through 10. it deletes until the end of a view. number. The "number of occurs to process" parameter specifies how many items should be taken from source_view. 4 are still in the view <* Deletes occurrence 2. V(10) VIEW CONTAINS I. I(2). 5. V(10) VIEW CONTAINS I. If it is greater than the size of source_view.Using INSERT Function DCL I INTEGER. ENDDCL MAP 27 TO I(1). no items from source_view will be taken (zero is assumed). I(10) RESIZE(V. 2. The target_view must be an occurring view. ENDDCL DELETE(V. so 3rd became 2nd <* DELETE Deletes occurrences of a view. 2) MAP I(1) TO J *> 27 <* MAP I(3) TO J *> NULL – 1st occurrence removed. V2. for instance. now there are only 3 <* Deletes only occurrences 2-3. Example . If there are not enough occurrences after the given position. J INTEGER. 20) MAP I(10) TO J *> 27 <* MAP I(15) TO J *> NULL – a new occurrence <* RESIZE(V. AppBuilder 2. V1. I(3).Using DELETE Function DCL I. Example . By default. J INTEGER. but the source_view may be any view. If a third argument is given. C. Views must be identical in structure. 5) MAP I(1) TO J *> 27 <* MAP I(10) TO J *> runtime error – too large subscript <* RESIZE(V. 2. C CHAR(10). V2) TRACE(C OF V1(1)) *> O1V1 TRACE(C OF V1(2)) *> O1V2 TRACE(C OF V1(3)) *> O2V2 TRACE(C OF V1(4)) *> Test <* <* <* <* 13-30 Platform Support and Target Language Specifics . V3) TRACE (C OF V1 (4)) *>O0V3 <* INSERT(V1. The "number of occurs to process" parameter specifies how many items should be taken from source_view. V2) *> runtime error <* REPLACE Replaces occurrences of the target view with occurrences from the source view. V3. If it is less than zero. Example . V2. If this from_position is invalid (less than zero or greater than the size of target_view). but source_view can be any view. W) *> Illegal: W does not have identical structure as V1 <* INSERT(V1. V3 VIEW CONTAINS I. starting from a specified position. no items from source_view will be taken (zero is assumed). a runtime error is issued. V2(2). W(10).Java Extensions W VIEW CONTAINS I. V3. V2(2). 27. 5. ENDDCL MAP “O1V1” TO C OF V1(1) MAP “O2V1” TO C OF V1(2) MAP “O1V2” TO C OF V2(1) MAP “O2V2” TO C OF V2(2) MAP “O0V3” TO C OF V3 MAP “Test” TO C OF V1(4) REPLACE(V1. REPLACE does not add occurrences. 2. all items from it will be used and a warning will be issued at runtime. 4. so only those occurrences that exist in the target view are replaced. ENDDCL MAP “O1V1” TO C OF V1(1) MAP “O2V1” TO C OF V1(2) MAP “O1V2” TO C OF V2(1) MAP “O2V2” TO C OF V2(2) MAP “O0V3” TO C OF V3 INSERT(V1. W(10). Views must be identical in structure. The target_view must be an occurring view. If it is greater than the size of source_view. V VIEW CONTAINS V1(10). W VIEW CONTAINS I.Using REPLACE Function DCL I INTEGER. V1. C. V VIEW CONTAINS V1(10). V2) TRACE(C OF V1(1)) *> O1V1 <* TRACE(C OF V1(2)) *> O1V2 <* TRACE(C OF V1(3)) *> O2V2 <* TRACE(C OF V1(4)) *> O2V1 <* INSERT (V1. The second parameter is the user-specified alias. V2) *> V1(10) is replaced with V2(1) <* PRAGMA CLASSIMPORT for Java In Java. etc. V2) *> runtime error <* REPLACE(V1. V3) TRACE (C OF V1(4)) *> O0V3 <* REPLACE(V1. constants. This is achieved by creating an alias for this class – variable of type OBJECT TYPE ‘Java class name’ with a default or user-specified name. 4.lang.System.lang. by using PRAGMA CLASSIMPORT. It can be changed to a more convenient name. Whenever any class that has static fields or methods is used in a rule (in OBJECT TYPE ‘…’ or OBJECT ‘…’ declaration) a default alias is created for it. to avoid ambiguity errors that may cause failures during prepare.’ is replaced with the underscore symbol(_) is created. then the default alias name (class name where the symbol ‘. this PRAGMA determines whether event handlers for window objects are assigned automatically. PRAGMA classimport (java. AppBuilder 2. and its static method exit() is invoked. This alias can be used to access static fields and methods of Java classes. The first parameter in the list is the Java style class name (case-sensitive). Example .System. however. method names. If a second parameter is not used. 5. PRAGMA CLASSIMPORT Syntax PRAGMA CLASSIMPORT ( class_or_alias ) where class_or_alias is the list of Java class names (and optionally the alias name) to import. 10. Separate the class and alias using a comma (spaces are ignored) and place the entire list in parentheses. PRAGMA CLASSIMPORT is used to make the static fields and methods of Java classes available for the rule.1. 27. system) system. Warning It is strongly advised that you choose a unique name for an alias when using ObjectSpeak names that are the same as keywords..1 Rules Language Reference Guide 13-31 .Using PRAGMA CLASSIMPORT to Create an Alias Alias system is created for class java.Java Extensions REPLACE (V1. so note the exact capitalization of the Java class name.exit(0) PRAGMA AUTOHANDLERS for Java PRAGMA AUTOHANDLERS ON OFF In Java. W) *> Illegal: W does not have identical structure as V1 <* REPLACE(V1. ObjectSpeak object types. The PRAGMA CLASSIMPORT clause is case-sensitive. ‘OK’ and ‘CANCEL’. P1.. regardless of whether PRAGMA AUTOHANDLERS is used. these handlers are not assigned. using the HANDLER statement. EDITREF OBJECT TYPE EDITFIELD.. and an edit field ‘EDIT’. The Handler for the event. Assume the following declarations: DCL BUTTON_OK OBJECT ‘OK’. is enabled automatically.. ENDPROC By default: • P1 is assigned for CLICK event of ‘OK’ pushbutton.. P2..PRAGMA AUTOHANDLERS In this example. EDITOR OBJECT ‘EDIT’.. If PRAGMA AUTOHANDLERS PRAGMA OFF statement is written in a rule. If you want to use P2 as a handler for CLICK event of ‘OK’ pushbutton. 13-32 Platform Support and Target Language Specifics . • P2 is assigned for CLICK event of ‘CANCEL’ pushbutton. however. if present.. ENDPROC PROC P2 FOR CLICK OBJECT TYPE BUTTON(EVT OBJECT TYPE CLICKEVENT) . • INIT – for INITIALIZE event of a window. ENDPROC PROC INIT FOR INITIALIZE OBJECT WINDOW . write: HANDLER BUTTON_OK (P2) If PRAGMA AUTOHANDLERS OFF is written. and P3 are not assigned automatically. All handlers for window objects are assigned upon rule startup.AbfGuiWindow).gui. INIT still is assigned for the INITIALIZE event of the window.Java Extensions The default value is ON. • P3 – for CLICK event of ‘EDIT’ edit field.. They can be assigned later. The only exception to this rule is the INITIALIZE event of the WINDOW class (Java class appbuilder. Example . BUTTONREF OBJECT TYPE PUSHBUTTON ENDDCL PROC P1 FOR CLICK OBJECT BUTTON_OK(EVT OBJECT TYPE CLICKEVENT) . the window associated with a rule has two push buttons. ENDPROC PROC P3 FOR CLICK OBJECT TYPE EDITFIELD(EVT OBJECT TYPE CLICKEVENT) . CHARDATA TO C MAP D.lang.tinal. • alias is the valid Rules identifier – alias for a method. alias ) where: • propertyname is the case-sensitive name of a property and the alias for which it is defined.tinal.tinal.PRAGMA ALIAS PROPERTY Class com. I INTEGER. DCL D OBJECT TYPE ‘com. Rules language identifiers are not case-sensitive and Java identifiers are case-sensitive. Therefore. however. ‘com.Data’ MAP D. two Java class properties whose names differ only in case cannot be used directly in rule code. CHARDATA) PRAGMA ALIAS PROPERTY(‘data’.tinal.DATA TO C *> invalid: field name “DATA” conflicts with field name “data” and can not be used directly<* PRAGMA ALIAS PROPERTY(‘DATA’.Data’. A rule. The identification string is considered to be casesensitive.Data has two fields: • data of type int and • DATA of type java.Java Extensions PRAGMA ALIAS PROPERTY for Java In Java. Rules Language provides the PRAGMA ALIAS PROPERTY clause for this purpose. • class_id is a string that identifies the implementation of the class.Data’. This alias can be used in Rules code instead of the method’s name.1 Rules Language Reference Guide 13-33 . ‘ class_id class_name ‘ . Example . PRAGMA ALIAS PROPERTY ( ‘ property_name ‘ . ‘com. INTDATA) MAP D.INTDATA TO I AppBuilder 2.Data’. • classname is the class name used in a rule’s code. can still access these methods by declaring aliases for them. ENDDCL D = NEW ‘com.String. It is not case-sensitive.1. It might be CLSID for OLE objects or the full Java class name for Java classes.tinal. C CHAR(100). NewBonus INTEGER. then this event handler is defined for all objects with the same system ID. INTEGER) DCL CurrentName VARCHAR(255). This allows you to define such a handler (others will be skipped silently). 10). For all systems IDs (HPSIDs) mentioned in the list. all column types must be listed when declaring an iterator (SQLJ analog for cursor). This list of types is determined by the code generation facility using list of target host variables of first FETCH from this cursor. In this case. there can be no FETCH from that particular cursor in the rule. where • cursor_name is any valid identifier • data_type is any primitive data type (any data type except views or objects) See “Data Types”. You may specify a list of specific system IDs to handle or specify ALL (indicates the list of all HPSIDs)..Java Extensions PRAGMA COMMONHANDLER for Java In Java. PRAGMA SQLCURSOR for Java In Java. you can use PRAGMA SQLCURSOR to define this cursor’s column types and avoid a preparation error.Pragma SQLCURSOR PRAGMA SQLCURSOR (myCurs. PRAGMA COMMONHANDLER ( ALL HPSID ) . If the cursor is not intended to be used in a FETCH statement. ENDDCL . Example . PRAGMA SQLCURSOR allows you to specify cursor field types without FETCHing all the cursor fields into the host variables. VARCHAR(255) DEC(31. SQL ASIS DECLARE MyCursor CURSOR FOR SELECT Name. Salary. Bonus FROM Employees WHERE Name = :CurrentName 13-34 Platform Support and Target Language Specifics . data_type ) . PRAGMA COMMONHANDLER allows you to specify the handler on any object’s event using the same system ID (HPSID) within the rule scope. In SQLJ. PRAGMA SQLCURSOR ( cursor_name.. the following rule applies: If an event handler is defined for the object with the same system ID (HPSID) as an object name. Button’ AppBuilder 2. Event Handler Statement in Java In Java.1.awt. only event handlers for the window objects are enabled automatically..Java Extensions ENDSQL . Usage By default. For all other objects. use the PRAGMA CLASSIMPORT clause. all event handlers are disabled. DCL p object to ‘java. Using a non-initialized object variable causes a runtime error.KeyListener’ type ‘java. handlers are also enabled automatically for the Rule object.Button are enabled for the object of that type. For Java generation.1 Rules Language Reference Guide 13-35 . Example .awt.awt. then an error is generated. See PRAGMA KEYWORD and PRAGMA CLASSIMPORT for Java for detailed syntax and examples. If any handler in the list is not defined for the object or there are several handlers for the same event and the same object. • event_handlers_list is the list of event handlers that are delimited with commas. When a rule is terminated. For additional information see“Compiler Pragmatic Statements”.event.awt.Button’.Enabling Event Handlers Two event handlers of type java. to use static and static final methods and variables of a class in a rule without creating an object of that class. the HANDLER clause enables event handlers for the specified object. SQL ASIS UPDATE Employees SET Bonus = :NewBonus WHERE CURRENT OF MyCursor ENDSQL Static and Static Final Methods and Variables in Java In Java. HANDLER Syntax HANDLER object_name ( event_handlers_list ) where: • object_name is the object variable. the HANDLER statement must be used to enable event handlers. KeyHandler1 proc for keyPressed listener ‘java.. KeyHandler2 proc for keyTyped listener ‘java.event.awt.awt.KeyListener’ object p ( evt object ‘java.Button’ ( evt object to ‘java.KeyEvent’ ). ENDDCL HANDLER p ( KeyHandler1. KeyHandler1 proc for keyPressed listener ‘java.KeyEvent’ ).awt. p1 like p.KeyEvent’ ). The behavior of overlay support in Java and HTML is not the same as doing a memory copy from the input to output as in other AppBuilder environments.event.awt.Button’.awt. KeyHandler2 ) Event handler is enabled for the object for which it was declared.KeyListener’ type ‘java.awt.event. The overlay is done using Java Reflection on the input and output views to create a byte stream from the input and to interpret the byte stream to create the output view.KeyHandler2 ) Error because KeyHandler was not defined for object p1. 13-36 Platform Support and Target Language Specifics .event. KeyHandler proc for keyPressed listener ‘java.Button’.KeyListener’ object p ( evt object to ‘java.Button’ ( evt object ‘java. which also goes through the input and output views to create a communications byte stream.Java Extensions ( evt object to ‘java. KeyHandler2 proc for keyTyped listener ‘java. to handle the overlay.awt. DCL p object ‘java.Button’.event.event.awt.awt.awt.awt.KeyEvent’ ).KeyEvent’ ) ENDDCL HANDLER p1 ( KeyHandler) *> error <* *> error <* OVERLAY Statements in Java In Java.awt.event.awt.awt. DCL p object ‘java.awt. ENDDCL HANDLER p ( KeyHandler1. AppBuilder uses the communications marshalling code.KeyEvent’ ) ENDDCL HANDLER p ( KeyHandler ) Error because KeyHandler1 and KeyHandler2 were declared for the same object. the OVERLAY statement can be used in Java (thick-client) and HTML (thin-client) applications.event.awt. KeyHandler proc for keyPressed listener ‘java.event.event. DCL p object to ‘java.KeyListener’ type ‘java.KeyListener’ object p ( evt object ‘java.event. • The given length of a CHAR field is used to read the byte stream. If there is any unexpected decimal in the string. • VARCHAR fields in the output view first reads two bytes of length from the byte stream and uses the length to read the actual data from the byte stream. • All data types are validated when the data is written to the output view based on the data type of the target field. • PIC (picture) fields are read as string and interpreted using the PICTURE format.) Example . The byte stream created from the input view is interpreted using the structure of the output view in the following way. variables of type OBJECT hold references to object instances. the byte stream is read as string and converted to decimal using the decimal conversion routines. • SMALLINT is interpreted as two bytes and INTEGER. But. which means the unused bytes are truncated and the actual length (two bytes) followed by the actual data is written in to the byte stream. It is better to avoid using a VARCHAR field within the output view because of the unexpected behavior. the reference to the existing object is assigned to it. • TIMESTAMP is interpreted as three four-byte values. (See “Creating a New Object Instance” for additional information. Having a picture field in the output view could give unexpected results.Assigning References to Objects DCL AppBuilder 2. If the first two bytes happen to have a length value less than the defined maximum length for the VARCHAR field. • VARCHAR is always interpreted with the actual length. each character occupies 2 bytes. it throws an exception. When assignment to that variable is performed.Java Extensions The following list describes how the input view is interpreted using Java Reflection: • DEC (decimal) is converted to a string representation and the string is written as bytes. • If the target field data type is DEC (decimal). as the information there also applies to Java.1. DATE. And a communications exception is thrown if a bad value is being mapped to any field.1 Rules Language Reference Guide 13-37 . DATE and TIME is interpreted as four bytes. The safest way to overlay in Java and thin-client is to use a target view that contains only CHAR fields and has a total length equal or greater than the source view. one byte for single-byte characters and 2 bytes for DBCS characters. • SMALLINT is interpreted as two bytes and INTEGER. • MIXED is converted to bytes. use the NEW clause. it reads the data. Assigning Object Data Type Variables in Java In Java. To create new instances of an object. • PIC (picture) fields are converted to a string using the PICTURE format and written as byte stream. and TIME are interpreted as four bytes. • TIMESTAMP is interpreted as three four-byte values. if the length is more than the maximum. it is thrown a communications exception. • CHAR is directly converted to bytes. • DBCS is converted to bytes. Refer to the information in OVERLAY Statement for a comprehensive understanding of OVERLAY statements. .GetWindow TO CHILD_WINDOW CONVERSE REPORT Statements in Java START and PRINTER in Java In Java mode. DETACH OBJECT Statement in Java In Java applications. *> Let “EXIT” be ID of EXIT button <* name char(100). USE RULE . it is possible to use final fields of Java classes as selectors in CASE clause. 13-38 Platform Support and Target Language Specifics .PRINTER printer_name START statement.. Every running rule is represented in Java by an instance of a Rule object (appbuilder. it will override the corresponding appbuilder. ENDDCL PROC assignExample MAP ExitButton to button1 *>Now button1 holds ref to EXIT button<* MAP button1 to button2 *>and button2 too <* MAP button2. Example . the caller rule can have some control over the called detached rule by using the DETACH OBJECT clause.gui. it is not checked whether these selectors are equal to other selectors in CASEOF statement. ENDDCL USE RULE CHILD_RULE DETACH OBJECT MY_CHILD_RULE *>CHILD_WINDOW holds reference to CHILD_RULE window<* MAP MY_CHILD_RULE. if you specify the printer name in CONVERSE REPORT. To access this instance..DETACH OBJECT DCL MY_CHILD_RULE OBJECT TYPE RULE. CHILD_WINDOW OBJECT TYPE WINDOW.ini setting and the report will be printed to a printer named "printer_name". Note If you use Java class final fields as selectors in CASEOF clause.AbfModule).Java Extensions button1.. this variable is assigned to an instance of the OBJECT Rule that is called.text to name *> name equals "EXIT" <* button2. you can put the name of a variable of type 'OBJECT Rule' in the DETACH OBJECT clause of the USE RULE statement and after the rule calls. Final field of Java class must be convertible to type of the field in CASEOF clause.text to name *> name equals "QUIT" <* ENDPROC CASEOF in Java In Java. button2 object type 'appbuilder.setText('QUIT') MAP ExitButton. ExitButton object 'EXIT'.AbfPushButton'. There will be no error message if recursion is used. • OBJECT data type. • The following functions are not supported: • ADDR(view) • OCCURS • CLEARNULL • ISNULL • GET_ROLLBACK_ONLY • SET_ROLLBACK_ONLY • HPSCOLOR • RGB • HPSERROR • HPSResetError • HPSErrorMessage • LOC(. AppBuilder 2.. • PRAGMA statement is restricted only to KEYWORD.) are not supported. • Decimal arithmetic CALCULATOR mode is not supported. • Decimal fields cannot be used with the TRACE function. DELETE. If a decimal field is used a code generation error message is received during preparation. method calls.1 Rules Language Reference Guide 13-39 . • SETDISPLAY and SETENCODING accept only LOOKUP and ERROR sets as parameters. but execution results will be unpredictable. • Dynamic occurring views and support functions such as APPEND..Restrictions in ClassicCOBOL For example: CONVERSE REPORT MyReport PRINTER "\\server\printer" START Restrictions in ClassicCOBOL The following is a list of the restrictions in Rules Language for ClassicCOBOL. ObjectSpeak and all related statements (NEW.1. These restrictions apply to all AppBuilder releases. INSERT.):OBJECT • Recursion is not supported for procedure calls. and RESIZE are not supported. • There is no macro support on any host platform. REPLACE. etc. Decimal Field Representation in ClassicCOBOL Decimal fields up to 18 decimal digits are represented as packed decimal data. Given the following declaration in the rule: dec_field_18_8 dec(18. To alleviate this difficulty. The DDL for decimal fields large than supported by the COBOL compiler differs from the DDL of OpenCOBOL fields. use the Initialization file parameter to specify that 13-40 Platform Support and Target Language Specifics . See code generation parameter -K. DDL in ClassicCOBOL In ClassicCOBOL. ClassicCOBOL stores these larger decimal fields in DB2 overlayed in a CHAR field. dec_field_25_8 dec(25.Specific Considerations for ClassicCOBOL Specific Considerations for ClassicCOBOL The following sections describe the specific differences in Rules Language elements for ClassicCOBOL: • Data Types in ClassicCOBOL • Variable for the Length of the VARCHAR Data Item in ClassicCOBOL • Size Limitations in COBOL • Comparing Views for ClassicCOBOL and OpenCOBOL • Functions in ClassicCOBOL • Double-Byte Character Set Functions in ClassicCOBOL • SETDISPLAY in ClassicCOBOL • OVERLAY Statements in ClassicCOBOL • Restrictions in OpenCOBOL Data Types in ClassicCOBOL This section contains special considerations for using data types in ClassicCOBOL. 03 X-PIC-V--LOC-DECL-0005 REDEFINES V--LOC-DECL-0005 PIC X(13). up to 31 decimal digits are supported and functions are provided when more digits are required than supported by the compiler. refer to the following section: Data Types.8). 03 X-PIC-V--LOC-DECL-0004 REDEFINES V--LOC-DECL-0004 PIC X(10). For more information on data types. * *** DEC_FIELD_25_8*** 03 V--LOC-DECL-0005 PIC X(13). The fields with more than 18 digits are represented as PIC data.8). This represents a significant difficulty if your existing applications use large fields to convert to OpenCOBOL. the following COBOL declaration will be used: * *** DEC_FIELD_18_8*** 03 V--LOC-DECL-0004 PIC S9(10)V9(8) USAGE COMP-3. a varied number of characters can fit into a particular MIXED field. Variable for the Length of the VARCHAR Data Item in ClassicCOBOL Changing _LEN only effects the _LEN variable. Conversion functions are also generated to convert the CHAR DB2 data to the packed decimal COBOL field. one for shift-out and one for shift-in. For more information on the DBCS and MIXED data types refer to the following section: “DBCS and MIXED Data Types”. a single DBCS character might occupy up to four(4) bytes . DBCS and MIXED Data Types in COBOL Because of the differences in character representation on different platforms. In COBOL. you can use any value for the _LEN variable.two for character code. each of which occupies one byte. For more information refer to the following section: Variable for the Length of the VARCHAR Data Item. a double-byte character occupies two bytes. Keep the following in mind when writing COBOL applications: A MIXED data item’s length is calculated in bytes in COBOL and can have a maximum length of 32K. behavior may be different. We do not recommend using the _LEN variable (modifying the VARCHAR variable through its _LEN variable in COBOL). In the beginning of a DBCS character sequence. Example 2 MAP "some string" TO VC MAP 0 TO VC_LEN IF VC = "" TRACE("VC is empty") AppBuilder 2. the corresponding VARCHAR is not effected immediately. For more information on the DEC data type refer to the following section: DEC.1. Therefore. it only affects the DDL of for this field. there is "shift-out" control character and the sequence is ended with a "shift-in" control character. In other constructions.Specific Considerations for ClassicCOBOL decimal fields greater than 31 be stored in a CHAR DB2 field. Thus. This parameter does not effect the COBOL field type which is pack decimal. a single-byte character occupies one byte. Changing the _LEN variable does not effect comparison.1 Rules Language Reference Guide 13-41 . Examples Example 1 MAP -1 TO VC_LEN MAP VC_LEN TO SomeVariable SomeVariable will contain –1. For more information see“RTRIM”. For more information. refer to the following section: View. but the returned string length cannot be greater than the length of the argument. refer to the following section: Comparing Views. data items larger than 16777215 bytes are not allowed. Size Limitations in COBOL In COBOL. This same limitation also applies to the number of occurrences. For more information. if RTRIM is applied to an invalid MIXED string. Functions in ClassicCOBOL The following functions have special considerations for ClassicCOBOL: • RTRIM in ClassicCOBOL • UPPER and LOWER in ClassicCOBOL • STRLEN in ClassicCOBOL • STRPOS in ClassicCOBOL • VERIFY in ClassicCOBOL • SUBSTR in ClassicCOBOL • Double-Byte Character Set Functions in ClassicCOBOL • SETDISPLAY in ClassicCOBOL RTRIM in ClassicCOBOL In COBOL.Specific Considerations for ClassicCOBOL ENDIF The trace statement will not be executed because the value of VC is not changed and equals “some string”. 13-42 Platform Support and Target Language Specifics . Because view comparison does not take into account the data type of the fields in the view. Comparing Views for ClassicCOBOL and OpenCOBOL View comparison is implemented as a native COBOL record comparison. the function result is undefined. it is possible for the comparison of two views to give a different result than the comparison of the fields in the view. For more information see“STRPOS”. the function parameter is not required to be a valid DBCS string. the function returns zero. In ClassicCOBOL. If STRLEN is applied to an invalid MIXED string. If both parameters of STRPOS are DBCS. VERIFY in ClassicCOBOL In ClassicCOBOL. if UPPER or LOWER is applied to an invalid DBCS or MIXED string. the function returns zero. the function returns zero. if one of the STRPOS parameters is an invalid MIXED string. it returns an empty string. the function result is undefined but it cannot be greater than the maximum length of the given string. this function can be applied to MIXED and DBCS strings. Position and length must specified in characters. STRLEN in ClassicCOBOL In ClassicCOBOL. the function will return an empty string. Characters are converted to upper case or lower case according to the specified codepage. STRPOS in ClassicCOBOL In ClassicCOBOL. For additional information. the function returns zero. those parameters do not have to be valid DBCS strings. If both parameters of the VERIFY are DBCS. if one of the VERIFY parameters is an invalid MIXED string. not bytes. AppBuilder 2. For more information see“SUBSTR”. For more information see“UPPER and LOWER”. the parameters can contain invalid characters. the function parameter is not required to be a valid DBCS string. if SUBSTR is applied to an invalid MIXED string. this codepage is specified by the R2C_CODEPAGE setting and requires recompiling rules after changing it. Shift control characters which appear in COBOL mode only are not counted.1.Specific Considerations for ClassicCOBOL UPPER and LOWER in ClassicCOBOL In ClassicCOBOL.1 Rules Language Reference Guide 13-43 . If the first parameter of the VERIFY is a valid MIXED string and the other is an invalid DBCS string. If the first parameter of STRPOS is a valid MIXED string and the together is an invalid DBCS string. For more information see“VERIFY”. SUBSTR in ClassicCOBOL In ClassicCOBOL. When SUBSTR is applied to a DBCS string. For more information see“UPPER and LOWER” and “UPPER and LOWER”. refer to Supported Codepages. when STRLEN is applied to a DBCS string. In ClassicCOBOL. it returns a normalized argument. See “DBCS and MIXED Data Types” and “SETDISPLAY”or details. 13-44 Platform Support and Target Language Specifics . This process is called normalization. it returns the argument with deleted empty DBCS portions and successive DBCS portions glued together. The string returned has the same length. SETDISPLAY in ClassicCOBOL In ClassicCOBOL. it is padded with single-byte spaces. If the display length is less than 39 characters. Note In this document. • DBCS function • With a CHAR and a MIXED argument. Some of these functions perform “Validation and Implementation”. it returns the argument with shift control characters added before (“shift-out” character) and after (“shift-in” character) given by the DBCS string. which bypasses the MAP statement safety mechanism. it assumes that the first and last characters of a given CHAR string are “shift-out” and “shift-in” control characters respectively and thus returns the argument with the first and last characters deleted. • Characters added before (“shift-out” character) and after (“shift-in” character) given by the DBCS string. but if it has been shortened by normalization. RTRIM is required for DBCS display if the display length is less than 39 characters (78 bytes plus 2 shift characters). • With a DBCS argument. This would be a problem because the DBCS conversion functions expect that the first and last bytes of a given string are shift control characters. it returns its argument. • MIXED function • With a CHAR and a MIXED argument.Specific Considerations for ClassicCOBOL Double-Byte Character Set Functions in ClassicCOBOL The following information pertains to the implementation of double-byte character set functions in ClassicCOBOL: • CHAR function • With a CHAR argument. for the statement OVERLAY var1 TO var2 var1 is the source and var2 is the destination. • With a DBCS argument. it returns its argument • With a MIXED argument. OVERLAY Statements in ClassicCOBOL The OVERLAY statement can be used in AppBuilder to perform a byte-by-byte memory copy. the returned value will be padded with single-byte characters. it depends on the COBOL compiler used and its options.Restrictions in OpenCOBOL Warning Data items of types MIXED and DBCS cannot. If subscript is out of range. If you are using OVERLAY statements in your applications with data types that are not explicitly mentioned in this book. Therefore. differences in the form that data types are stored in may affect the behavior of your programs. refer to the Enterprise Administration Guide. Although MAP carefully compares view structures to make sure that data ends up only in fields like those from which it came. there are no corresponding COBOL functions. Caution The OVERLAY statement can cause unexpected results. Refer to the information in OVERLAY Statement for a comprehensive understanding of OVERLAY statements. Use caution when using OVERLAY—erroneous OVERLAY statements might not be noticed during compilation but can result in problems during execution. There is no guarantee that such applications can be ported to other platforms or supported from release to release. OVERLAY blindly copies all the source data item’s data. in its stored form. as a precautionary measure.1. Enterprise Application Guide and the Enterprise Rebuild Guide. Also. we urge you to use MAP statements (see caution note below) in all cases where OVERLAY statements are not necessary.1 Rules Language Reference Guide 13-45 . These restrictions apply to built-in Rules Language functions because. to the destination data item. Restrictions in OpenCOBOL The differences between COBOL and Rules Language lead to several restrictions to OpenCOBOL generation. in any circumstance. be used in OVERLAY statements. a system exception can occur. Specific details about OpenCOBOL using Rules Language are documented throughout this manual. AppBuilder 2. as the information there also applies to ClassicCOBOL. in some cases. Subscript Control in ClassicCOBOL Runtime support does not perform subscript control of occurring views. All the restrictions and variations in behavior are described in this guide in the specific sections related to each function. be aware that such applications are vulnerable to future failure. For more information about OpenCOBOL implementation. • Macro is not supported on any mainframe platforms. Therefore.Restrictions in OpenCOBOL The following is a list of the restrictions in Rules Language for ClassicCOBOL. the OpenCOBOL generation option GENNOSUFF may be used to prevent the generation of mixed COBOL identifiers. OVERLAY is one example of an affected function. this will result in COBOL names containing DBCS and non-DBCS characters. but execution results will be unpredictable. etc) are not supported. which may affect some of the statements. The preparation will not issue any error messages. When GENNOSUFF is used. see “FRACTION in OpenCOBOL” for details. • INT and DECIMAL functions ignore second parameter (format string). However the COBOL compiler issues error messaged if the generated COBOL code is not correct. and CONVERSE REPORT statements are not supported. • Recursion is not supported for procedure calls. Customizing ABNLS C module will provide the required functionary. CONVERSE WINDOW. REPLACE. • Decimal arithmetic CALCULATOR and COMPATIBILITY modes are not supported. • Dynamic occurring views and support functions APPEND. There will be no error message if recursion is used. • CONVERSE. INSERT. ObjectSpeak and all related statements(NEW. • Global views are not supported. • Set symbol decimal part is truncated if it is longer than declared in the set. • The OpenCOBOL support library is not customized for any DBCS codepage. • DBCS object names are not supported. method calls. • PRAGMA statement is restricted only to KEYWORD. which is not supported by the IBM COBOL compiler and results in a COBOL compiler error. such as RETURN-CODE. DBCS and MIXED identifiers used in Rules code are not supported. • No data validation is performed on DBCS and MIXED data. • If Set Define values contain DBCS characters. These restrictions apply to all AppBuilder releases. • FRACTION returns microseconds only. and TIMESTAMP representation is different from all other platforms. COBOL only allows the use of the Roman alphabet for program identifiers. DATE. • OBJECT data type. DELETE. • 3270 converse mainframe system components are not supported. It is best to avoid the use of DBCS characters for define values. If Define values contain only DBCS characters. • TIME. • TIMESTAMP precision is up to the microseconds only. it should be used for the entire application. Be careful when defining object names to avoid the generation of COBOL reserved words. • The following statements are not supported: • START TRANSACTION • COMMIT TRANSACTION • ROLLBACK TRANSACTION • The following functions are not supported: • ADDR(view) 13-46 Platform Support and Target Language Specifics . and RESIZE are not supported. • SETDISPLAY and SETENCODING accept only LOOKUP and ERROR sets as parameters. .):OBJECT The following is an OpenCOBOL client side generation only restriction and applies to all releases: • DBCS and MIXED data types are not supported.1 Rules Language Reference Guide 13-47 .1.Specific Considerations for OpenCOBOL • OCCURS • CLEARNULL • ISNULL • GET_ROLLBACK_ONLY • SET_ROLLBACK_ONLY • HPSCOLOR • RGB • HPSERROR • HPSResetError • HPSErrorMessage • LOC(.. Specific Considerations for OpenCOBOL The following sections describe the specific differences in Rules Language elements for OpenCOBOL: • Double-Byte Character Set Functions in ClassicCOBOL • Data Types for OpenCOBOL • Using DEC with OpenCOBOL • Using DEC with OpenCOBOL • Variable for the Length of the VARCHAR Data Item in OpenCOBOL • Comparing Views for ClassicCOBOL and OpenCOBOL • Views in OpenCOBOL • Size Limitations in COBOL • Symbol in OpenCOBOL • Functions in OpenCOBOL • Double-Byte Character Set Functions in OpenCOBOL • SETDISPLAY in OpenCOBOL • OVERLAY Statements in OpenCOBOL • OVERLAY Statements in OpenCOBOL • Use Rule Statement in OpenCOBOL • PERFORM Statement (PROC) in OpenCOBOL • PRAGMA CENTURY for OpenCOBOL AppBuilder 2. Therefore. Given the following declarations in the rule: dec_field_18_8 dec(18. • User-friendly code. The new facility does not replace the existing COBOL capability. One externally-callable COBOL program is generated from each AppBuilder rule. For more information on the DEC data type refer to the following section: DEC. The OpenCOBOL facility does not require the use of a separate runtime. as does ClassicCOBOL. Generated OpenCOBOL is readable and maintainable outside the AppBuilder environment. External libraries required by the generated COBOL are provided in the source. as well as the compiled code. Programs are not collapsed together. but rather provides an alternative code generation option. DEC-FIELD-25-8-F PIC S9(17)V9(8) USAGE COMP-3. For more information on data types.8). 13-48 Platform Support and Target Language Specifics . the following declaration will be used in OpenCOBOL program: 03 03 DEC-FIELD-18-8-F PIC S9(10)V9(8) USAGE COMP-3. there is a one-to-one relationship between AppBuilder rules and each generated COBOL program.Specific Considerations for OpenCOBOL OpenCOBOL Generation The AppBuilder code generation facility introduces a new method of generating OpenCOBOL that is readable and maintainable and closely conforms to standard COBOL. Thus. • Standardized data types and functions. it only creates packed decimal fields in DB2 for its decimal data. Generated OpenCOBOL is callable without an intermediary runtime. Data Types for OpenCOBOL This section contains special considerations for using data types in OpenCOBOL. refer to the following section: Data Types.8). All libraries required by the generated COBOL are delivered in source and binary form. Generated OpenCOBOL uses industry-standard data types and standard COBOL functions where available. • The option to prepare standard COBOL or OpenCOBOL. using standard functions and data formats where possible. dec_field_25_8 dec(25. Using DEC with OpenCOBOL OpenCOBOL only supports as many decimal digits as supported by the compiler. Important features include: • Runtime-free code generation. %0y. Table 13-1 OpenCOBOL Data Type Descriptions Data Type DATE TIME TIMESTAMP COBOL Picture PIC X(10) PIC X(12) PIC X(26) Format Example YYYY-MM-DD HH. COBOL equivalents.MM. TIME and CHAR functions. format string.nnnnnnn.ss. %Y • CHAR function for TIME fields: %h.mm.FFFFFF In OpenCOBOL.HH. You can safely modify the _LEN field of VARCHAR(n) in the 0…n range in OpenCOBOL. yyyy-mm-dd). AppBuilder 2. and the format examples for each type. where nnnnnnn is microseconds. TIMESTAMP fields are stored as a PIC X(26) character field in the format yyyy-mmdd-hh. %m. Variable for the Length of the VARCHAR Data Item in OpenCOBOL You can assign any value to the _LEN variable. %0m. %x • TIME function: %0h.SS. %0t. %x In all other cases support library call is generated. %d. %0s. a configurable character format is used. Table 13-1 compares the data types. %0d. %0f.. %0c. TIME fields are stored as PIC X (12) character fields. %y. %0j. %0f. %s. %0t. %0h.g. For more information on the DATE and TIME data types refer to the following section: Date and Time Data Types. Example: MAP -1 TO VC_LEN MAP VC_LEN TO SomeVariable SomeVariable will contain –1. %Y • DATE function: %0m. For more information refer to the following section: Variable for the Length of the VARCHAR Data Item. %0y. thus they are ten(10) bytes in length. another is to generate COBOL code that will implement the function. for a function is a constant and this format string contains only the following tokens only: • CHAR function for DATE fields: %0m.MM.FFF YYYY-MM-DD. %f.1. Native COBOL code is generated only when second parameter. %0c. %m.1 Rules Language Reference Guide 13-49 . %j. TIMESTAMP In OpenCOBOL. %0s. %c. %0m.Specific Considerations for OpenCOBOL Using Date and Time with OpenCOBOL OpenCOBOL uses two ways to generate COBOL code for DATE. %t. The TIME variable has a length of twelve bytes. In OpenCOBOL. DATE fields are stored as PIC X(10) character fields that correspond to your DB2 configuration (e. One way is to generate a call to a support library routine.SS. %0d. This facility functions similarly in OpenCOBOL. etc.Specific Considerations for OpenCOBOL However. ENDDCL MAP "12345" TO VC1 MAP 10 TO VC1_LEN MAP VC1 TO VC2 MAP VC2 ++ "A" TO VC2 VC2 will contain ‘12345 A’ (five spaces before A). VARCHAR(20). For more information. therefore. refer to the following section: Symbol. views. 13-50 Platform Support and Target Language Specifics . assigning an invalid value (less than zero) results in a runtime error when the corresponding VARCHAR value is required. Symbol in OpenCOBOL In OpenCOBOL. It can be set either by adding FLAG=C5SET to the Hps. OpenCOBOL uses the AppBuilder system ID to refer to fields. The COBOL compiler will issue an error identifier in the generated program is the same as a COBOL reserved word. in cases where the view name is longer than thirty characters. if a set symbol is an integer or a smallint. the value of the corresponding variable will be filled with spaces up to the actual length (the length defined by the _LEN variable). No verification on coincidence with COBOL reserved words is performed.ini file or by specifying -FC5SET as a code generation parameter. If you assign the _LEN field a value greater than the declared VARCHAR maximum length. DCL VC1 VC2 VARCHAR(5). AppBuilder creates a generic name. sets. Views in OpenCOBOL The current AppBuilder COBOL generation facility generates one copybook from each view.1. The maximum length for a name in COBOL is thirty characters. it can be generated with the USAGE COMP5 clause which is supported only in COBOL for Z/OS 3. when using -fVERDT. Therefore. Remember. only the format string is analyzed. The first parameter is assumed to be correct. then if the DATE function returns an invalid date or the TIME function returns an invalid TIME. when the DATE and TIME functions are generated without a support library call. Note In cases where AppBuilder generates COBOL code for DATE/TiME functions without a call to the support library (where -fVERDT has not been set in the code generation parameter). AppBuilder 2.ini file or by specifying -FVERDT on the PARM line under the OPENCOBOLGEN header in the CODEGEN member of your CGTABLES. both DATE and TIME functions will be verified. However. then the result value also will be invalid. A returned TIME value can contain an invalid time. see “DATE and TIME”.1. such as the 13th month. if the first parameter is not valid for the format string specified by the second parameter.1 Rules Language Reference Guide 13-51 . For more information. the returned value is converted to a special value so that INT function will return -1 when applied to that value.Specific Considerations for OpenCOBOL Functions in OpenCOBOL The following functions have special considerations for OpenCOBOL: • Date and Time Functions in OpenCOBOL • INT in OpenCOBOL • FRACTION in OpenCOBOL • RTRIM in OpenCOBOL • UPPER and LOWER in OpenCOBOL • STRLEN in OpenCOBOL • STRPOS in OpenCOBOL • VERIFY in OpenCOBOL • SUBSTR in OpenCOBOL • Double-Byte Character Set Functions in OpenCOBOL • SETDISPLAY in OpenCOBOL Date and Time Functions in OpenCOBOL In OpenCOBOL. you can force DATE and TIME to be validated if you specify the VERDT code generation parameter. This parameter can be set either by adding FLAG= VERDT to the [COBOL] section of the hps. See below for an example of the latter method: &BASEQUAL. the results are not verified by default and a returned DATE value can contain an invalid date. such as the 29th hour. This may cause COBOL runtime to throw an exception if the value is then used in other function calls or expressions.CGTABLE(CODEGEN) [OPENCOBOLGEN] PARM=PARAM=-VMC -fdyncall -yz -fverdt If -fVERDT is added to the code generation parameter. INT function will return an invalid result not -1 when applied to such a value. refer to Supported Codepages. If STRLEN is applied to an invalid MIXED string. For more information see“STRLEN”. the function result is undefined.53. See FRACTION for more information.Specific Considerations for OpenCOBOL INT in OpenCOBOL In OpenCOBOL. If the first parameter of STRPOS is a valid MIXED string and the together is an invalid DBCS string. 13-52 Platform Support and Target Language Specifics . this codepage is specified by the R2C_CODEPAGE setting and requires recompiling rules after changing it. when the INT function is applied to an invalid DATE/TIME value. UPPER and LOWER in OpenCOBOL In OpenCOBOL. the function returns zero. In OpenCOBOL. STRPOS in OpenCOBOL In OpenCOBOL. if RTRIM is applied to an invalid MIXED string. FRACTION in OpenCOBOL This function will return the fraction part with the precision available in the timestamp field.976428 then FRACTION applied to this field returns 428000000. the function parameter is not required to be a valid DBCS string. it returns an empty string. If both parameters of STRPOS are DBCS. For more information see“STRPOS”. For additional information. if UPPER is applied to an invalid DBCS or MIXED string. those parameters do not have to be valid DBCS strings. the function returns zero. Characters are converted to upper case according to the specified codepage.48. if one of the STRPOS parameters is an invalid MIXED string. For more information see“RTRIM”. STRLEN in OpenCOBOL In OpenCOBOL. For more information see“UPPER and LOWER”and “UPPER and LOWER”. the function result is undefined but it cannot be greater than the maximum length of the given string. it will not always return -1. For example if the timestamp field has the value 2003-08-21-12. See the DATE/TIME verification notes in the “DATE/TIME Expressions” description or “INT” for more details. when STRLEN is applied to a DBCS string. but the returned string length cannot be greater than the length of the argument. RTRIM in OpenCOBOL In OpenCOBOL. Shift control characters which appear in COBOL mode only are not counted. • With a DBCS argument. Some of these functions perform “Validation and Implementation”. Double-Byte Character Set Functions in OpenCOBOL In OpenCOBOL.1. This process is called normalization. validation verifies that the shift control characters are balanced. it returns a normalized argument. The string returned has the same length.Specific Considerations for OpenCOBOL VERIFY in OpenCOBOL In OpenCOBOL. it returns the argument with shift control characters added before (“shift-out” character) and after (“shift-in” character) given by the DBCS string. For more information see“VERIFY”.1 Rules Language Reference Guide 13-53 . it is padded with single-byte spaces. if one of the VERIFY parameters is an invalid MIXED string. The following information pertains to the implementation of double-byte character set functions in OpenCOBOL: • CHAR function • With a CHAR argument. but if it has been shortened by normalization. the function will return an empty string. • With a DBCS argument. it returns its argument. the parameters can contain invalid characters. • DBCS function • With a CHAR and a MIXED argument. AppBuilder 2. the function returns spaces. it returns its argument • With a MIXED argument. the function returns zero. For more information see“SUBSTR”. • With a DBCS argument. If validation fails. the function returns zero. it returns the argument with deleted empty DBCS portions and successive DBCS portions glued together. When SUBSTR is applied to a DBCS string. it returns a normalized argument. • With a MIXED argument. the function parameter is not required to be a valid DBCS string. If the first parameter of the VERIFY is a valid MIXED string and the other is an invalid DBCS string. if SUBSTR is applied to an invalid MIXED string. SUBSTR in OpenCOBOL In OpenCOBOL. • MIXED function • With a CHAR and a MIXED argument. it assumes that the first and last characters of a given CHAR string are “shift-out” and “shift-in” control characters respectively and thus returns the argument with the first and last characters deleted. it returns the argument with shift control characters added before (“shift-out” character) and after (“shift-in” character) given by the DBCS string. If both parameters of the VERIFY are DBCS. This would be a problem because the DBCS conversion functions expect that the first and last bytes of a given string are shift control characters. See “Double-Byte Character Set Functions in OpenCOBOL” and “SETDISPLAY”or details. SMALLINT. DATE. as the information there also applies to OpenCOBOL. the result may differ from the data types in COBOL: DCL integer_1 small_1. date_1.Specific Considerations for OpenCOBOL SETDISPLAY in OpenCOBOL In OpenCOBOL. the OVERLAY statement logic remains the same as in ClassicCOBOL. 13-54 Platform Support and Target Language Specifics . the returned value will be padded with single-byte characters. view_2 VIEW CONTAINS integer_1. RTRIM is required for DBCS display if the display length is less than 39 characters (78 bytes plus 2 shift characters). If you mix data types in an overlay. SMALLINT. view_1 VIEW CONTAINS date_1. Refer to specific data type descriptions in “Data Types” to review the differences. DATE. small_2 date_1 INTEGER. integer_1 OF view_2 will contain a different value than if you ran this example for COBOL. view_1 VIEW CONTAINS small_1. date_1. small_1. small_2. small_2. OVERLAY Statements in OpenCOBOL In OpenCOBOL. ENDDCL MAP DATE TO date_1 OF view_1 OVERLAY view_1 TO view_2 Since DATE type representation in OpenCOBOL differs from that in COBOL. The only difference originates from differences in data types. Refer to the information in OVERLAY Statement for a comprehensive understanding of OVERLAY statements. If the display length is less than 39 characters. since both DATE variables have the same offset. view_2 VIEW CONTAINS integer_1. It is safe to overlay fields of the same data type with the same offset in source and destination views. small_2 date_1 INTEGER. OpenCOBOL Example: DCL integer_1 small_1. date_1. ENDDCL MAP DATE TO date_1 OF view_1 OVERLAY view_1 TO view_2 The result of this OVERLAY statement example is that date_1 OF view_2 is set to the same value as date_1 OF view_1. See Table 14-5 for OpenCOBOL specific settings. ENDDCL //DEFAULT_CENTURY value from the ini file will be used SET d:=date(“12/28/99”. in cases where the procedure name is longer than 30 characters.Specific Considerations for OpenCOBOL Use Rule Statement in OpenCOBOL OpenCOBOL calling conventions are different from runtime-managed COBOL and are completely non-interoperable. This statement overrides the DEFAULT_CENTURY INI setting. There will be no error message if recursion is used but execution results will be unpredictable. The next PRAGMA CENTURY statement overrides the previous one and behaves as described above. Recursion is not supported for procedure calls. The maximum length for a paragraph name in COBOL is 30 Characters. PRAGMA CENTURY ( string_literal ) where • string_literal is any character literal containing one or two digits Example . therefore. The AppBuilder USE RULE statement is converted to individual program calls using a dynamic COBOL call. PRAGMA CENTURY for OpenCOBOL In OpenCOBOL. These generated programs cannot invoke one another. No verification is performed on coincidence with COBOL reserved words. PRAGMA CENTURY allows you to specify the default century that is used in the conversion functions DATE(char) and CHAR(date). AppBuilder creates a generic name.1 Rules Language Reference Guide 13-55 .”%0m/%0d/%0y”) TRACE(d)//will print 1899-12-28 PRAGMA CENTURY(“20”) AppBuilder 2.PRAGMA CENTURY DCL d DATE. The HPSCOMMAREA is not used. PERFORM Statement (PROC) in OpenCOBOL The generated OpenCOBOL paragraph name is equivalent to the AppBuilder Rules Language name.1. For example: MOVE 'ZAAQQ26' TO TMP-19-F CALL TMP-19-F USING INPUT-VIEW-V OUTPUT-VIEW-V For more information see “USE RULE Statement”.”%0m/%0d/%0y”) TRACE(d)//will print 1999-12-28 PRAGMA CENTURY(“18”) SET d:=date(“12/28/99”. PRAGMA CENTURY effects all DATE and CHAR functions that follow it until the end of the Rule code or another PRAGMA CENTURY statement. 3. Not DBCS-certified.1 host • Target language restrictions with a 2.3.1 host Target Language Function ADDR(view) APPEND DELETE INSERT C X X X X Java X X X X OpenCOBOL 13-56 Platform Support and Target Language Specifics . it depends on the COBOL compiler used and its options. a system exception can occur.1 mainframe Restrictions Not DBCS-certified.3. Target Language Support Tables Items marked with an X in the tables below are not supported in that release for that target language.2 mainframe OpenCOBOL restrictions: • TIMESTAMP function precision is up to the hundredth of a second only.1.1 client and a 2.1.0. • • • • INCR is not supported. Release Specific Considerations Table 13-2 lists the restriction for specific releases. • None of the support library modules are reentrant. ClassicCOBOL and OpenCOBOL restriction: • Numeric conversion functions are not supported.0.1.”%0m/%0d/%0y”) TRACE(d)//will print 2099-12-28 Subscript Control in OpenCOBOL Runtime support does not perform subscript control of occurring views.2 host Table 13-3 Target language restrictions with a 2.1.0. The following tables summarize support by release: • Target language restrictions with a 2.1n AppBuilder 2.1. AppBuilder 2. Items marked with an asterisk (*) sign are deprecated and may be removed in future releases. Table 13-2 Restrictions specific to releases Release AppBuilder 2.Release Specific Considerations SET d:=date(“12/28/99”. • DBCS and MIXED data types are not supported. Predefined macros are not supported with the exception of except LANGUAGE and ENVIRONMENT. DECR is not supported.1. If subscript is out of range.2 client and a 2.1 client and a 2. PRAGMA SQLCURSOR is not supported. 1.char) DATE(timestamp) DATE(char) DATE(integer) DATE(char.char) DATE(mixed) X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X C X X Java OpenCOBOL X X AppBuilder 2.char) DATE(dbcs.mixed) CHAR(time.Target Language Support Tables Table 13-3 Target language restrictions with a 2. char) CHAR(time.1.1 Rules Language Reference Guide 13-57 . mixed) DBCS(dbcs) DBCS(char) DBCS(mixed) MIXED(mixed) MIXED(char) MIXED(dbcs) DATE DATE(dbcs) DATE(dbcs. char) CHAR(dec. char) CHAR(time) CHAR(date) CHAR(date.1 host Target Language Function REPLACE RESIZE OCCURS SIZEOF CLEARNULL ISNULL CEIL FLOOR ROUND TRUNC INCR DECR CHAR(integer) CHAR(char) CHAR(dbcs) CHAR(mixed) CHAR(dec) CHAR(integer. char) CHAR(date.1.1 client and a 2. char) DECIMAL(char) DECIMAL(char.char) TIME(dbcs.1.1.char) INT(char.1 client and a 2.integer) HOURS(time) MONTH(date) YEAR(date) DAY(date) DAY_OF_YEAR(date) DAY_OF_WEEK(date) MILSECS(time) MINUTES(time) MINUTES_OF_DAY NEW_TO_OLD_DATE(date) NEW_TO_OLD_TIME(time) OLD_TO_NEW_DATE(integer) OLD_TO_NEW_TIME(integer) SECONDS(time) SECONDS_OF_DAY(time) INT(char) INT(time) INT(date) INT(char.1 host Target Language Function DATE(mixed.mixed) TIME TIME(integer) TIME(dbcs) TIME(dbcs.mixed) TIME(timestamp) TIME(char) TIME(char.char) TIMESTAMP TIMESTAMP(date.char) DECIMAL(char.mixed) TIME(mixed) TIME(mixed.Target Language Support Tables Table 13-3 Target language restrictions with a 2.char) DATE(mixed.time.char) TIME(mixed.char.char.char) FRACTION(timestamp) GET_ROLLBACK_ONLY X X X X X X X X X X X X X X X X X X X X X X X X C X X Java X X OpenCOBOL X X 13-58 Platform Support and Target Language Specifics . 1 Rules Language Reference Guide 13-59 .mixed) VERIFY(mixed.1 client and a 2.integer):dbcs X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X C X X Java OpenCOBOL X X X X X X AppBuilder 2.Target Language Support Tables Table 13-3 Target language restrictions with a 2.1.1.char):smallint STRPOS(mixed.integer):char SUBSTR(dbcs.1.1 host Target Language Function SET_ROLLBACK_ONLY HPSCOLOR(integer) RGB(integer.integer):char SUBSTR(char.integer.mixed):smallint STRPOS(mixed.char):smallint VERIFY(dbcs.integer) HPSERROR HpsResetError HpsErrorMessage(integer) LOC(view):CHAR LOC(view):OBJECT LOC(integer):OBJECT LOC(smallint):OBJECT LOC(smallint):OBJECT LOC(char):OBJECT LOC(dbcs):OBJECT LOC(mixed):OBJECT LOC(dec):OBJECT LOC(date):OBJECT LOC(time):OBJECT LOC(timestamp):OBJECT LOC(boolean):OBJECT LOC(object):OBJECT VERIFY(char.integer.dbcs) LOWER(char):char LOWER(dbcs):dbcs LOWER(mixed):mixed UPPER(char):char UPPER(dbcs):dbcs UPPER(mixed):mixed STRLEN(char):smallint STRLEN(dbcs):smallint STRLEN(mixed):smallint STRPOS(char.char) VERIFY(mixed.char) VERIFY(mixed.dbcs):smallint SUBSTR(char. char.1.integer.0.Target Language Support Tables Table 13-3 Target language restrictions with a 2.integer.integer):mixed RTRIM(char):char RTRIM(dbcs):dbcs RTRIM(mixed):mixed LOOKUP and ERROR set types SetDisplay X X X X X X X X C X X X X X Java X X X X X OpenCOBOL X X X X X Table 13-4 Target language restrictions with a 2.2 host Target language Function ADDR(view) APPEND DELETE INSERT REPLACE RESIZE OCCURS SIZEOF CLEARNULL ISNULL CEIL FLOOR ROUND TRUNC INCR DECR CHAR(integer) CHAR(char) CHAR(dbcs) CHAR(mixed) CHAR(dec) CHAR(integer. char) CHAR(time) CHAR(date) X X X X X X X X X X X X X X X X X X X X X X X X X X X C X X X X X X Java X X X X X X X X X X X ClassicCOBOL OpenCOBO L 13-60 Platform Support and Target Language Specifics .1 client and a 2.integer. char) CHAR(dec.integer):dbcs SUBSTR(mixed.1. integer):dbcs SUBSTR(mixed.3.integer):mixed SUBSTR(dbcs.0.2 client and a 2.1 host Target Language Function SUBSTR(mixed. char) CHAR(dec.3.integer):mixed SUBSTR(dbcs. char) CHAR(date.char) TIME(dbcs.char) TIME(mixed.Target Language Support Tables Table 13-4 Target language restrictions with a 2. mixed) CHAR(time.0. mixed) DBCS(dbcs) DBCS(char) DBCS(mixed) MIXED(mixed) MIXED(char) MIXED(dbcs) DATE DATE(dbcs) DATE(dbcs.3.char) TIMESTAMP TIMESTAMP(date. char) CHAR(time.0.1.char) DATE(mixed.time.mixed) TIME(mixed) TIME(mixed.char) DATE(dbcs.3.2 client and a 2.char) DATE(mixed) DATE(mixed.mixed) TIME(char) TIME(char.mixed) TIME TIME(integer) TIME(timestamp) TIME(dbcs) TIME(dbcs.2 host Target language Function CHAR(date.char) DATE(timestamp) DATE(char) DATE(integer) DATE(char.integer) HOURS(time) MONTH(date) YEAR(date) DAY(date) DAY_OF_YEAR(date) X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X C Java ClassicCOBOL OpenCOBO L AppBuilder 2.1 Rules Language Reference Guide 13-61 . char.char) INT(char.Target Language Support Tables Table 13-4 Target language restrictions with a 2.2 host Target language Function DAY_OF_WEEK(date) MILSECS(time) MINUTES(time) MINUTES_OF_DAY NEW_TO_OLD_DATE(date) NEW_TO_OLD_TIME(time) OLD_TO_NEW_DATE(integer) OLD_TO_NEW_TIME(integer) SECONDS(time) SECONDS_OF_DAY(time) INT(char) INT(time) INT(date) INT(char.integer) HPSERROR HpsResetError HpsErrorMessage(integer) LOC(view):CHAR LOC(view):OBJECT LOC(integer):OBJECT LOC(smallint):OBJECT LOC(smallint):OBJECT LOC(char):OBJECT LOC(dbcs):OBJECT LOC(mixed):OBJECT LOC(dec):OBJECT LOC(date):OBJECT LOC(time):OBJECT LOC(timestamp):OBJECT LOC(boolean):OBJECT X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X C Java ClassicCOBOL OpenCOBO L 13-62 Platform Support and Target Language Specifics .0.0.2 client and a 2.char.char) DECIMAL(char) DECIMAL(char.char) DECIMAL(char.integer.char) FRACTION(timestamp) GET_ROLLBACK_ONLY SET_ROLLBACK_ONLY HPSCOLOR(integer) RGB(integer.3.3. integer):mixed RTRIM(char):char RTRIM(dbcs):dbcs RTRIM(mixed):mixed LOOKUP and ERROR set types SetDisplay X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X C X Java ClassicCOBOL X OpenCOBO L X AppBuilder 2. integer):dbcs SUBSTR(dbcs.integer):char SUBSTR(char.1.integer):mixed SUBSTR(mixed.char):smallint STRPOS(mixed.dbcs):smallint SUBSTR(char.integer):dbcs SUBSTR(mixed.integer):mixed SUBSTR(mixed.integer.integer):dbcs SUBSTR(dbcs.mixed) VERIFY(mixed.Target Language Support Tables Table 13-4 Target language restrictions with a 2.char) VERIFY(mixed.char):smallint VERIFY(dbcs.2 host Target language Function LOC(object):OBJECT VERIFY(char.1 Rules Language Reference Guide 13-63 .integer.0.3.char) VERIFY(mixed.integer):char SUBSTR(dbcs.integer.0.2 client and a 2.dbcs) LOWER(char):char LOWER(dbcs):dbcs LOWER(mixed):mixed UPPER(char):char UPPER(dbcs):dbcs UPPER(mixed):mixed STRLEN(char):smallint STRLEN(dbcs):smallint STRLEN(mixed):smallint STRPOS(char.mixed):smallint STRPOS(mixed.3.integer. Target Language Support Tables 13-64 Platform Support and Target Language Specifics . AppBuilder comes with predefined parameters optimized for most applications.CGTABLE(CODGEN) where n is the version number of the repository.1.USERn.1 Rules Language Reference There are many parameters used by the code generation facility.1.CHAPTER 14 CODE GENERATION PARAMETERS AND SETTINGS AppBuilder 2.DSN=HPSLE. Use caution when changing any of the predefined parameters to avoid unexpected results. AppBuilder 2.1 Rules Language Reference 14-1 . See the following sections: • Code Generation Parameters • INI File Settings • Command line parameters settings • Processing Order for Parameters • Code Generator restrictions • Supported Codepages Code Generation Parameters Parameters that control code generation options can be specified from the command line or in the hps.ini file for the workstation products. For mainframe products parameters can be specified either in the EXEC statement or in the code generation INI file defined by the DD: //CFG DD DISP=SHR. Each flag must be specified on a separate line. They are divided into sections.This list is added to the end of the command line parameters.Code Generation Parameters INI File Settings INI files on the workstation and the mainframe have similar structures. See Processing Order for Parameters for additional information. The following sections are used by the code generation facility and are language and platform independent: • [Codegen] • [CODEGENPARAMETERS] • [MacroDomains] • [MacroDefinitions] • [CodegenPragmas] The following sections are used by the code generation facility and are language and platform dependent. [Codegen] See the following tables for settings available in the Codegen section: • General settings for the Codegen section • Workstation specific settings • Host specific settings The following table lists general settings. and descriptions in the Codegen section. PARAM <listparameters> FLAG <flag_name> 14-2 Code Generation Parameters and Settings . A line starting with semicolon in the first position is the comment line. The total number of flags cannot exceed 32. For example the flag NOGENSUFF can be defined as FLAG=NOGENSUFF. This is used to specify additional code generation parameters or flags. For a list of flags see Command Line Parameters. sample values. These settings will overwrite settings from the language and platform independent sections if applicable. • [OpenCobolGen] • [CobolGen] • [CGen] • [CServerGen] • [JavaGen] • [JavaServerGen] • [JavaHTMLGen] See also Settings Available in All Sections. Settings in these sections apply to only one target language. Table 14-1 General settings for the Codegen section Settings Sample Values Descriptions This setting is used to list additional code generation parameters. and descriptions for the workstation only. See C{C[S|C]|B|J[S|C|H]|O{Y|N|B}} parameter for additional values. Code page used for DBCS string functions. sample values.MS G e:\AppBuilder\temp e:\AppBuilder\ad\cfg\cg e:\AppBuilder\ad\cfg\cg e:\AppBuilder\temp e:\AppBuilder\temp e:\AppBuilder\temp e:\AppBuilder\temp e:\AppBuilder\bnd e:\AppBuilder\temp e:\AppBuilder\temp e:\AppBuilder\temp e:\AppBuilder\temp Descriptions Location of the codegen error message file Location of codegen data files Location of other codegen data files Directory to find temporary BLD files Directory to create all temporary work files Directory to create output files Directory to find rule source Directory to find window panel files Directory to find rule bind file Directory to create RC files Directory to create VW files Directory to create temporary error list files Directory to create listing with rule preparation results The following table lists settings.Code Generation Parameters Table 14-1 General settings for the Codegen section Settings Sample Values Descriptions This setting defines the language and environment. B is for COBOL.1. J is for Java. Table 14-2 Workstation specific settings Settings R2C_MSG_FILE R2C_TABS_DIR R2C_CODEGEN_DIR R2C_BLD_DIR R2C_WORK_DIR R2C_OUTPUT_DIR R2C_SOURCE_DIR R2C_PNL_DIR R2C_BINDFILE_DIR R2C_RC_DIR R2C_VW_DIR R2C_ERR_DIR R2C_LST_DIR Sample Values e:\AppBuilder\ad\cfg\cg\cg. sample values.IBM-933 descriptions Location of the codegen error message file Valid for Cobol and OpenCobol only. This setting defines the codepage for Cobol generation. AppBuilder 2. Table 14-3 Host specific settings Settings R2C_MSG_FILE R2C_CODEPAGE Sample Values DD:CFG(CG) Ko_KR. and descriptions for the mainframe only. The default is C. R2C_CODEGEN_TYPE C R2C_CODEPAGE The following table lists settings.1 Rules Language Reference 14-3 . See Supported Codepages for additional information. For example the first character from NLSIN will be replaced with the first character in NLSOUT. See C function setlocale for more details on acceptable values. For Java see DEFAULT_DATE_FORMAT in appbuilder. This format is used to convert date fields when calling DB2 Valid for C and COBOL only. Use NLSTABLE to run codegen with a codepage that is different than the current locale. When the long name is converted all characters in the name included in NLSIN will be replaced with characters from NLSOUT which have the same index. Table 14-4 General parameters in the CODEGENPARAMETERS section Settings Sample Values Descriptions Valid for C.%0s <character_sequence_1> NLSOUT <character_sequence_2> NLSTABLE . The specified codepage support must be installed on the machine. COBOL and OpenCobol. DFLTDTFMT %0m/%0d/%Y DFLTTMFMT %0t:%0m:%0s DB2DTFMT DB2TMFMT NLSIN %Y-%0m-%0d %0t. and descriptions in the CODEGENPARAMETERS section. COBOL and OpenCobol.ini Valid for C. See the following tables for available settings: • General parameters in the CODEGENPARAMETERS section • OpenCOBOL specific settings • Java specific settings • C specific settings The following table lists general settings. No verification is done and the resulting name may be ambiguous.ini Valid for C and COBOL only.Code Generation Parameters [CODEGENPARAMETERS] The CODEGENPARAMETERS section contains parameters that control how the code is generated.%0m. If character_sequence_1 and character_sequence_2 have different lengths then the longer one will be truncated. sample values. This format is used for date and char functions when the second parameter was omitted.932 14-4 Code Generation Parameters and Settings . This format is used to convert time fields when calling DB2 If both values NLSIN and NLSOUT are defined then they are used to convert all long names from repository or the DCL ENDDCL section. This format is used for time and char functions when second parameter was omitted for Java see DEFAULT_TIME_FORMAT in appbuilder. Only delimiters can be changed by the end user. the date values are converted to integer values and then compared. This value is used to initialize TIME type fields.00. This value is also passed to the support library functions. The default value is 1900.00.00. See DATEDB2CMP. This setting controls how date comparisons are generated.00.00.000000 DEFAULT_CENTURY 1900 DATEDB2CMP 0001-01-01 DATEDB2DFLT 0001-01-01 TIMESTAMPDB2CMP 0001-01-01-00.000000 CompareDatesAsString N AppBuilder 2. See DATEDB2DFLT for more details.00.INI. This is the value to compare all host Date values with. the rule must be re-prepared.Code Generation Parameters The settings in the following table are supported for OpenCOBOL only.%0s.000000 TIMESTAMPDB2DFLT 0001-01-01-00. In all other cases.1 Rules Language Reference 14-5 . This is the value for the century in the DATE function when only two digits are used for the year in the input and format strings. This value would be added to the two digit year when parsed. If set to Y.00. The value to assign to a TIMESTAMP host variable if it is less than TIMESTAMPDB2CMP.000 0000-00-00-00. This value is used to initialize TIMESTAMP type fields. date fields are compared as strings where the result is defined by the environment. If set to N. This format is used when a support library function is called.1. The value to assign to a DATE host variable if the variable is less than DATEDB2CMP. In AB2032 string comparison is used only in host variables.%0m.ini and DEFAULT_CENTURY in the [AE Runtime] section of the HPS. date fields are converted to integer values and compared. To change this value for runtime. This comparison is platform independent.00. See also DEFAULT_CENTURY in appbuilder. Table 14-5 OpenCOBOL specific settings Settings DATEFMT Sample Values %Y-%0m-%0d Descriptions This format is used when a support library function is called. DATEINIT 0000-00-00 TIMEFMT %0t. See TIMESTAMPDB2DFLT for more details. This setting can be overridden by PRAGMA CENTURY statement. The value to compare all host TIMESTAMP variables with.%0f TIMEINIT TIMESTAMPINIT 00. This value is used to initialize DATE type fields. Only delimiters can be changed by the end user. Code Generation Parameters Table 14-5 OpenCOBOL specific settings Settings Sample Values Descriptions This controls whether SQL-INIT-FLAG will be reset to 0 in each rule. By default DB2 creates a connection with AutoCommit set to TRUE which disables all transaction control. Table 14-6 Java specific settings Settings SYSTEMVIEWPACKAGE GLOBAL_PACKAGE SET_PACKAGE VIEW_PACKAGE COMPONENT_PACKAGE set view component Sample Values appbuilder. By default SQL-INIT-FLAG is not initialized. Table 14-7 C specific settings Settings INDEX_CONTROL_ON INDEX_CONTROL_ABORT Sample Values YES NO Descriptions Specify if generated C code should perform index checking when accessing occurring views. Possible values are YES or NO. Values: YES or NO Specify if rule should abort at execution time if index is out of bounds when accessing occurring views. This is the name of the package to use for sets. Specifies whether or not to split the view to the elementary fields or use reflection based when performing CLEAR(view). This is the name of the package to use for all rules. This is the name of the package to use for components.systemviews Descriptions This is the name of the system view package. Specifies whether or not to split the view to view mapping up to the elementary fields or use the reflection based map() method. no call will be generated. If the AUTOCOMMIT key is not set. This is the name of the package to use for views. Generated Java code will have setAutoCommit() call with a parameter equal to the value specified by AUTOCOMMIT (casesensitive). Values: YES or NO 14-6 Code Generation Parameters and Settings . Possible values are YES or NO. If setting is equal to 0 then MOVE ZERO TO SQL-INITFLAG will be generated for each database rule. To enable transaction control with SQL statements COMMIT and ROLLBACK connection method setAutoCommit(false) must be invoked. SQLINITFLAG 0 The settings in the following table are supported only for Java. AUTOCOMMIT false REFLECTION_VIEW_MAP YES STATIC_CLEAR YES The settings in the following table are supported only for C. Code Generation Parameters [MacroDomains] This section contains Macro Domains definitions. See “Macro Value Validation” for more information. Table 14-8 Settings LANGUAGE ENVIRONMENT Sample Values Java,C,Cobol,OpenCobol Server,HTML,GUI Descriptions This setting defines all possible values for macro LANGAUGE. This setting defines all possible values for macro ENVIRONMENT. [MacroDefinitions] This sections defines macros that can be used for all target languages and platforms. The MacroDefinitions section can be viewed and updated from Construction Workbench > Tools > Workbench Options > Preparation tab > Conditionals button. [CodegenPragmas] <pragma_line> ... <pragma_line> where pragma_line has correct Rules Language syntax. See “Compiler Pragmatic Statements”. [OpenCobolGen] This section contain values that will overwrite any settings from the common sections and is used only for OpenCOBOL. [CobolGen] This section contain values that will overwrite any settings from the common sections and is used only for ClassicCOBOL. [CGen] This section contain values that will overwrite any settings from the common sections and is used only for C. [CServerGen] This section contain values that will overwrite any settings from the common sections and is used only for C. AppBuilder 2.1.1 Rules Language Reference 14-7 Code Generation Parameters [JavaGen] This section contain values that will overwrite any settings from the common sections and is used only for Java. [JavaServerGen] This section contain values that will overwrite any settings from the common sections and is used only for Java. [JavaHTMLGen] This section contain values that will overwrite any settings from the common sections and is used only for Java. Settings Available in All Sections The following table lists settings, sample values, and descriptions of parameters that can be used in the following sections: • [OpenCobolGen] • [CobolGen] • [CGen] • [CServerGen] • [JavaGen] • [JavaServerGen] • [JavaHTMLGen] Table 14-9 Settings available in all language specific code generation sections Settings MACRO PARM Sample Values LANGUAGE=Java ENVIROMENT=GUI PARAM=<listparameters> Descriptions This defines a macro that is language or environment specific. This overwrites the PARAM setting from the [Codegen] section. This overwrites the setting from the [CodegenParameters] section with name ParameterName giving it the value paramter_value. Specifies the location of the code generator data file. Specifies the extension to use for all generated programs PARM <ParamterName>=<paramter_value > R2C_STANDARD_TABS R2C_OUT_EXT e:\AppBuilder\ad\cfg\cg\javas.tab .java Examples of settings in language specific sections [JavaGen] R2C_STANDARD_TABS=e:\AppBuilder\ad\cfg\cg\javas.tab 14-8 Code Generation Parameters and Settings Code Generation Parameters ; location of code generator data file R2C_OUT_EXT=.java ; extension to use for all generated programs MACRO=LANGUAGE=Java MACRO=ENVIRONMENT=GUI ; define a macro that is language or environment specific [COBOLGEN] R2C_STANDARD_TABS=DD:CFG(COBOLTAB) ; location of code generator data file PARM=PARAM= -H -VMO -!O -J -YG ; Default parameters setting for COBOL generation [OPENCOBOLGEN] R2C_STANDARD_TABS=DD:CFG(OCOBOLT) PARM=PARAM= -VMC -fdyncall -yz ; Default parameters setting for Open COBOL generation PARM=DATEINIT=0000/00/00 Additional Code Generation Settings The DECIMAL_ARITHMETIC_MODE setting in the AP Windows-NT section of the INI file defines the arithmetic used in the generated program. Three values are supported: • COMPATIBILITY for HPS532 compatibility • COBOL for COBOL compatibility • CALCULATOR uses calculator rules and is compatible HPS540 NT. This value must be set using the configurator. Command line parameters settings Additional code generation parameters may be set from the command line. These parameters may also be listed as values on the PARAM ini file setting. Each parameter must being with the dash symbol (-). Parameters must be divided by at least one space. Parameters are not case sensitive with the exception of –P. See Processing Order for Parameters for more information. General Parameters If restrictions are not specifically mentioned in the parameter description, the parameter can be used for all platforms, languages, and environments. -C{C[S|C]|B|J[S|C|H]|O{Y|N|B}} This parameter defines the language and environment as follows: • -C generates a C program. The second letter defines environment as follows: AppBuilder 2.1.1 Rules Language Reference 14-9 Code Generation Parameters • S - server • C - client • -B generates a ClassicCOBOL program. • -J generates for Java generation.The second letter defines environment as follows: • S - server (EJB or RMI) • C - client (Java client) • H - HTML / Servlet • -O generates for OpenCOBOL. The second letter defines environment for user calls as follows: • Y passes the parameters DFHEIBLK and HPSCOMMAREA • N passes only the input and output views as parameters. This is the default value. • B passes dummy DFHEIBLK and HPSCOMMAREA along with the input and output views. Example -CB -C specifies that ClassicCOBOL is generated. B specifies that dummy DFHEIBLK and HPSCOMMAREA are passed along with the input and output views. -F<flag_name> This parameter is used to specify additional code generation parameters referred to as flags. For example, the flag NOGENSUFF can be passed to code generator as –FNOGENSUFF. See also FLAG for setting this in the INI file. -H This parameter generates conversion code for all host variables before and after SQL calls. This parameter is valid for C and ClassicCOBOL only. -J This parameter enables DBCS support. -Pparm_name=value This parameter has the following restrictions: • The parm_name cannot have spaces or equal (=) symbols. • The value starts with the first symbol after equal (=) sign and ends with the first space. • The value after equal (=) sign is case-sensitive. -yk Use this setting to disable new keywords. See Appendix A, “Reserved Words”. 14-10 Code Generation Parameters and Settings Code Generation Parameters -V{ M{N|O|C} | T{N|O} | C {L|S}} This setting controls how some constructs are generated as follows: • M defines how to generate and evaluate math statements. • N use compile time optimization and CALCULATOR mode. • O is compatible with HPS 5.3 and without compile time optimization. This is default value. • C use COBOL rules • T defines how to generate subtraction INT - TIME: • N produces TIME value (DEFAULT). • O produces INT value. • C defines how to format ClassicCOBOL code. • L uses long name based identifiers. • S uses short/implementation name based identifiers. This is the default. -yp[<pragma_line>] The <pragma line> must specify pragma construction with Rules Language syntax. For example: -yp[pragma keywords off (object)] -yxmacro_name=macro_value This parameter defines macro with the name specified by macro_name and the value specified by macro_value. The following restrictions apply: • The macro_name and macro_value cannot contain spaces or the equals (=) symbol. • The parm_name and macro_value after the equal (=) sign are case-sensitive. Example: -YXTARGET=Java Macro definitions can also be set in the ini files. See [MacroDefinitions] for more details. AppBuilder 2.1.1 Rules Language Reference 14-11 Code Generation Parameters -F<option name> The following options can be specified in the parameter list using –F<option name>: • CMNT Include user’s comments from the rule in the generated code. • NOSRC Do not include rule source lines in the generated code. • NOLINE Do not include rule source line number information in the generated code. This option is not supported for C. • MEXCI Use case-insensitive comparison in macros. • PNC Normally code generator verifies that calls between rules are used for the supported platform only. With this flag there will be no verification. In this case it is developers responsibility to ensure that generated code is correct. • URCOPT Disables optimization for unreachable code. This is not supported for ClassicCOBOL or OpenCOBOL. Workstation Specific Parameters Unless otherwise noted in the parameter description, settings can be used for all supported languages and environments. -ym Specifies which macro preprocessor is invoked by the code generator. -YC{ C | PL/1 | COBOL | OPENCOBOL | Assembler} This parameter is used only for Client side OpenCobol. It sets the language for generated view, and specifies copybooks used during component and set preparation. OCDIR This option is used only for client-side OpenCobol and can be specified in the parameter list using the -F<option name>. If the option is specified, then views will be generated in <R2C_OUTPUT_DIR>\view and sets will be generated in <R2C_OUTPUT_DIR>\set where <R2C_OUTPUT_DIR> is the value from HPS.INI. If the rule has not views or sets attached, then it is not necessary for either directory to exists or they may be empty. If this option is not specified, views and sets will be generated to <R2C_OUTPUT_DIR>. SCCOPY This option is used only for client-side OpenCobol and can be specified in the parameter list using -F<option name>. If this option is specified, only copybooks for sets and views are generated. Generated copybooks language is determined by the -YC parameter. 14-12 Code Generation Parameters and Settings Code Generation Parameters -E{D|B|R|O|V|C|W|E|L|A|T|SVO|SSO|SVB|SVP|SSB|SSP|SSC|SSA}<Ext> This parameter defines the extension for files types as specified by the following second letters. The <Ext> must include the leading period (.). • I - LOG file extension • X - CGMEX file extension • B - bind file extension • G - output bind file extension • R - rule file extension • O - generated C or COBOL file extension • C - RC file extension • W - VW file extension • E - errors file extension • L - listing file extension • T - tables file extension • P - panel file extension • Q - tree file extension • D - BLD file extension • H - Panel script file extension • K - RW script file extension • SVO - OpenCOBOL View copybook • SSO - OpenCOBOL Set copybook • SVB - Component View Cobol copybook • SVP - Component View PL\1 copybook • SSB - Set Cobol copybook • SSP - Set PL\1 copybook • SSC - Set C copybook • SSA - Set Assembler Source Example -EC.C This sets extension for generated C code to 'C' instead of 'PCC' which is the default. AppBuilder 2.1.1 Rules Language Reference 14-13 Code Generation Parameters -D{D|K|O|S|B|C|W|E|L|T|Q|A|G|M|F|N|P}<File/DirName> This defines the directory or file name for the following files: • B - directory that contains bind file • C - RC file directory • D - BLD file directory • E - errors file directory • F - config file name • G - CodeGen home directory • I - LOG file directory, DEFAULT WorkDir • K - work directory for temporary files • L - listing file directory • M - messages file name • N - standard CodeGen tables name • O - directory that contains generated C or COBOL program • P - directory that contains panel file • Q - tree files directory • S - directory that contains source rule file • T - tables file name • W - VW file directory • X - directory that contains generated CGMEX file, DEFAULT WorkDir • H - panel script file directory • R - RW script file directory -N{D|Q|T|E|B|P} This parameter specifies the name of the file to use during code generation as follows: • X - CGMEX file name • I - LOG file name • Q - tree file name • T - tables file name • E - error file name • D - BLD file name • B - Bind file name • P - panel file name • H - panel script file name • R - RW script file name 14-14 Code Generation Parameters and Settings Code Generation Parameters -G<country> This parameter has the same functionality as NLSTABLE in the INI file. ClassicCOBOL and OpenCOBOL Specific Parameters These parameters are only supported for ClassicCOBOL and OpenCOBOL. -YZ In OpenCOBOL this disables DATE and TIMESTAMP verification which normally occurs before they are passed to SQL statements. In ClassicCOBOL this disables generating IF ( ... < 367 ), which verifies that the date value is correct when converting an AppBuilder date to an SQL date and back. For more details, see the description of ini file settings DATEDB2CMP and TIMESTAMPDB2CMP. -yi This parameter uses the INITIALIZE statement to initialize or CLEAR views. The generated code will use the INITIALIZE statement to initialize views instead of the MOVE SPACES/ MOVE ZEROES method. View Initialization Parameters also affect how views are initialized. View Initialization Parameters The parameters in this section are supported only for ClassicCOBOL and OpenCOBOL unless otherwise noted. The default parameters provide a logically correct application; however, it may not be the best performance alternative. AppBuilder provides several optional code generation parameters. Analyze and test your application to determine which parameters work best for your application. For example, you can choose between the INITIALIZE statement and the older MOVE SPACES / MOVE ZEROES method. There are also several options that use statically-initialized structures in COBOL working storage that map to the identical structure. You should determine which is best for your installation. The MOVE SPACES / MOVE ZEROES default may be more efficient if your views have an OCCURS clause because the INITIALIZE view statement generates more assembler statements in the COBOL II compiler. Views available for a rule fall into two categories: • Views visible only for a given rule: These are local variables, auxiliary and temporary variables used in generated views and BINDFILE views declared as Working views. These views are put into the WORKING-STORAGE section during code generation. • External views, visible to other rules and components: These are rules and components, input/ output views, and global views. These views are put into the LINKAGE section during code generation. All WORKING-STORAGE and some LINKAGE section views are required to be initialized at the beginning of rule execution. AppBuilder 2.1.1 Rules Language Reference 14-15 14-16 Code Generation Parameters and Settings . it also increases the size of the load module by the size of the views. then move the COPY structure to the view during initialization. the -YI parameter is ignored. In this case. • LVI • WVI • IP • SWVI LVI This parameter initializes the linkage view statically. the -YI parameter is ignored. a subsequent rule call may lead to an error. A view copy is created in working storage and initialized statically. The "MOVE copy TO view" statement is used each time the view is initialized or the CLEAR statement is used. The following options can be specified in the parameter list using –F<option name>. A program is in its initial state when: • Data items having VALUE clauses are set to the specified value. the –YI parameter is ignored. A view copy is created in working storage and initialized statically. • Altered GOTOs and PERFORM statements are set to their initial states and internal files are closed. IP This parameter generates the INITIAL property. However. When the CLEAR statement is used. The INITIAL property places a program and any programs it contains in their initial states. -YG This parameter enables global view support. WVI This parameter initializes the working storage view statically. this can improve performance significantly. otherwise. occurring views. In this case. This may requiring maintenance if the application must be moved because of disk space considerations. ClassicCOBOL Specific Parameters These parameters are only supported for ClassicCOBOL. the view is initialized using the INITIALIZE statement. and number of numeric fields. The rule code must take care of its local and working view initialization. AppBuilder may create a duplicate copy of the view in COBOL working storage. Only one flag can be used at a time. The "MOVE copy TO view" statement is used each time the view is initialized. SWVI This is not supported in OpenCOBOL. Depending on view sizes. This parameter initializes working storage view statically using the VALUE clause. In this case.Code Generation Parameters If specified. This is the opposite of YQM. Do not use the GENNOSUFF parameter unless you verify that no objects generated conflict with AppBuilder Rules reserved words. This is the default. it will fail in the link step because only rule implementation names are supported at link time. This phrase is used only when same-name mapping is performed and when its syntax is the same as Rules Language syntax. • -YQF generates full qualification for the fields in the view. rather than generating RETURN_CODE_F. NN must be a number between 15 and 31. if the field RETURN_CODE is used in a rule. AppBuilder 2. “Reserved Words”.Code Generation Parameters -KNN All expressions with decimal fields with lengths less than NN will be generated using native COBOL arithmetic. • -YQU generates only those qualifications that were used in the rule source. or the name of other parts of your application. the generated code may contain name conflicts or reserved words that generate COBOL compile errors. -yd When this parameter is set the GOTO DEPENDING ON statement in the beginning of a COBOL rule will be not generated. MOVEC This will use MOVE CORRESPONDING instead of the MOVE statement when generating view to view mapping.1. For example. an invalid local variable. DB2 reserved words. LONGNAME This parameter generates long names for PROGRAM-ID and for the called rule names. OpenCOBOL Specific Parameters The following parameters affect the style of the generated code: • -YQM generates the minimum number of qualifications for the fields in the view. If this option is used during preparation. COBOL reserved words.1 Rules Language Reference 14-17 . If you use the GENNOSUFF parameter which generates objects without suffixes. The default value is 18. The following options can be specified in the parameter list using –F<option name>: GENNOSUFF Suffixes are generated by default. -YO and -!O Setting either of these parameters enables generation of additional parameters for HCGOPER call. -VMO is required for -!O. the generated COBOL field will be RETURN_CODE. When this flag is not used the rule implementation name is used for PROGRAM-ID and for the called rule names. This flag can only be used for code generation. Refer to Appendix A. 1. String concatenation and some other constructions are less efficient in this case. When the flag is used. When flag is used. RTCALL Generates all Date/Time/Char conversion functions as library calls. no line numbers are generated. NOVIEW do not generate copybooks for views and sets.Code Generation Parameters NOLINE Controls inclusion and generation of source line numbers information in the generated Java and COBOL code. NOSSR Generate more efficient and readable COBOL code without support for COBOL compiler SSRANGE option. GENPERIOD Generate period after each Cobol statement. NOSSR is the default. the generated code for all rules statements with exception of TRACE is safe to be used with SSRANGE COBOL compiler option. If NOSSR is not specified. CodeGen DYNCALL Generates a dynamic rule calls. 14-18 Code Generation Parameters and Settings . NOVIEW Does not generate view and set copybooks. NOSRC Controls inclusion of rule source code in the generated code for all platforms. ICW Ignores converse window statements VERDT Generates extra COBOL code to verify of Date/Time function result when format function is generated without support library call. C5SET Use COMP-5 for generating set symbol values if set symbol is integer or smallint. The COMP-5 clause is supported only in COBOL for Z/OS 3. They are generated by default. They are generated by default. no rule source code is generated. JAVASTYLE This option can be specified in the parameter list using –F<option name>. If this parameter is specified.Code Generation Parameters The main source for incompatibility with the COBOL compiler SSRANGE option is empty VARCHAR fields which have length 0. This parameter also disables effect of INDEX_CONTROL_ON and INDEX_CONTROL_ABORT Hps.1 Rules Language Reference 14-19 . If subscript is out of range the application may abort or may not. Java generation parameters The following parameters are supported for Java generation only. } instead of private void initListeners() { createListeners(). } GENSYSVIEW This option can be specified in the parameter list using –F<option name>. but 0 is not allowed in the reference modification for COBOL. For example: private void initListeners() { createListeners().1. If set the Java generation will use Java style for code blocks instead of C style. including any subview classes. C specific parameters The following parameter is supported for C generation only. the first occurrence is not assumed. -yd This parameter disables the generation of debugging information. AppBuilder 2. in either case. Rule syntax checking is not performed. -I This parameter disables the generation of index checking for subscripted views. System views are not generated by default. no index checking routines are generated. With this flag the Rules Language generates only main rule input and output view classes. IOVIEW This option can be specified in the parameter list using –F<option name>.ini settings. It generates system views. Code Generator restrictions Rules Language generates programs in C. It is not possible to give the exact number of the nested constructions supported because each construction requires different resources. the parameter processed last takes precedence. The parameters are read from the left to right and processed one by one. 3. However. 4. All other command line parameters are processed. the approximate number of nested constructions is 100. Java or COBOL languages. The INI file and platform independent sections are read.Code Generation Parameters DYNAMICMAP This option can be specified in the parameter list using –F<option name>. 5. the number of nested constructions is limited. Though this limit is large enough for most applications. Language depended sections are processed. For example. target language. creating a rule with more than one hundred nested loops or if statements will exceed the limit. conflicts. or overwriting. 2. parameters are not verified against platform. All compiler limits for the target languages apply to generated program. If the target platform was not specified on the command line and a value is specified in the INI file. This flag splits the view up to the elementary fields when doing CLEAR(view) instead of using reflection based clear() method. The command line is parsed to determine the location of the INI file and the target language and environment if they are different from the default settings. See also REFLECTION_VIEW_MAP INI setting. All default values are set. This flag forces the generation of reflection based map() method instead of splitting the view up to the elementary fields. it can be exceeded artificially. See also STATIC_CLEAR INI setting. 14-20 Code Generation Parameters and Settings . it will be used. STATICCLEAR This option can be specified in the parameter list using –F<option name>. In most cases. In addition. Processing Order for Parameters All settings are processed in the following order: 1. Table N-10 Codepage names for Japanese and Korean locales Ja_JP.IBM-930 Ja_JP.IBM-1390 Ja_JP. specifically the OS/390 C/C++ Programing Guide (Appendix D).IBM-939 Ja_JP. AppBuilder 2.The following table lists all the codepage names for Japanese and Korean locales.IBM-290 Ja_JP.IBM-1027 Ja_JP.Supported Codepages Supported Codepages The RC2_CODEPAGE parameter of the Hps. The codepage setting is used by several string functions when working with MIXED or DBCS values.1.IBM-1364 For a list of all the possible values for codepages refer to IBM’s documentation.IBM-1399 Ko_KR.IBM-933 Ko_KR. For example.1 Rules Language Reference 14-21 .ini file defines the codepage in both ClassicCOBOL and OpenCOBOL modes on the host. the function UPPER(DBCS) uses this setting. Supported Codepages 14-22 Code Generation Parameters and Settings . This allows you to compile the application with AppBuilder but prohibits you from using the functionality embodied in the new keywords. refer to the following tables: • Keywords for C that can be disabled with -YK • Keywords for Java that can be disabled with -YK • Keywords for ClassicCOBOL that can be disabled with -YK • Keywords for OpenCOBOL that can be disabled with -YK Table A-1 AND BREAK CATCH CLEAR Reserved words for Java APPEND BY CEIL CLOSE ASIS CASE CHAR CLOSELOG BASED CASEOF CLASS COMMIT AppBuilder 2.4. For applications written prior to HPS 5. refer to the following tables: • Keywords for C that can be disabled with PRAGMA KEYWORD • Keywords for Java that can be disabled with PRAGMA KEYWORD • Keywords for ClassicCOBOL that can be disabled with PRAGMA KEYWORD • Keywords for OpenCOBOL that can be disabled with PRAGMA KEYWORD For keywords that can be disabled with -YK. Refer to the following tables: • Reserved words for C • Reserved words for Java • Reserved words for ClassicCOBOL • Reserved words for OpenCOBOL For keywords that can be disabled with PRAGMA KEYWORD.1. The lists of reserved words are slightly different for each target language. Using a reserved word results in syntax errors when you prepare your rule.1.1 Rules Language Reference Guide Reserved words have special meaning in the Rules Language. You cannot use these words to name entities or variables in your application. you can disable some of the keywords by including the line PARAM=-yk in the [CodeGenParameters] section of HPS.INI (see [CODEGENPARAMETERS] section) or with help of PRAGMA KEYWORD statement (see “PRAGMA KEYWORD”).APPENDIX A Note RESERVED WORDS AppBuilder 2.1 Rules Language Reference Guide A-1 . Table A-1 Reserved words for Java CONTAINS DATE DBCS DELETE DOUBLE ENDDCL ENDSQL EXTERN FLOOR GOTO HOURS INIT INT LIKE LOWER MINUTES_OF_DAY MONTH NEW_TO_OLD_TIME OCCURS OPEN OVERLAY PRAGMA PTR REPORT ROLLBACK SECONDS SETDISPLAY SQL STRING SUBSTR TIME TRANSACTION TYPE VERIFY WHILE CONTINUE DAY DCL DETACH ELSE ENDDO ENDTRY FALSE FOR HANDLER IF INSERT INTEGER LISTENER MAP MIXED NEST NOT OF OPENLOG PERFORM PRINT REDEFINE RESIZE ROUND SECONDS_OF_DAY SETENCODING START STRLEN SWITCH TIMESTAMP TRUE UPPER VIA WINDOW CONVERSE DAY_OF_WEEK DEC DIV END ENDIF EVENT FETCH FRACTION HIGH_VALUES IN INSET INTO LOC MILSECS MOD NEW NOWAIT OLD_TO_NEW_DATE OR PIC PRINTER DEFINES RETURN RTRIM SECTION SIZEOF STARTINTERNAL STRPOS TERMINAL TO TRUNC USE VIEW WITH COMPONENT CURSOR DAY_OF_YEAR DECLARE DO ENDCASE ENDPROC EXCEPTION FLOAT FROM HOLD INDEX INSTANCE ISCLEAR LOW_VALUES MINUTES MODULE NEW_TO_OLD_DATE OBJECT OLD_TO_NEW_TIME OTHER POINTER PROC REPLACE RGB RULE SET SMALLINT STARTTIME SUBHEADER THROW TRACE TRY VARCHAR VOID YEAR A-2 Reserved Words . 1.1 Rules Language Reference Guide A-3 .Table A-2 BREAK Keywords for Java that can be disabled with PRAGMA KEYWORD CATCH CURSOR EXCEPTION FOR INTO OBJECT REDEFINES THROW VIA CLASS DECLARE FALSE GOTO LISTENER OPEN SET TRUE VOID CLOSE DOUBLE FETCH HANDLER MODULE PTR STRING TRY WITH CONTINUE ENDTRY FLOAT HOLD NEW REDIFINE SWITCH TYPE Table A-3 Keywords for Java that can be disabled with -YK FALSE GOTO LISTENER OPEN STRING TRUE VOID Reserved words for C ASIS CASE CHAR COMMIT CONVERSE DAY_OF_YEAR DETACH ELSE ENDDO ENDTRY FALSE FRACTION HOURS HPSResetError INIT INTEGER LOW_VALUES MINUTES MODULE NEW_TO_OLD_TIME OCCURES BASED CASEOF CLASS COMPONENT DATE DBCS DIV END ENDIF EVENT FLOAT FROM HPSColor IF INSET ISCLEAR LOWER MUNTES_OF_DAY MONTH NOT OF BREAK CATCH CLEAR CONTAINS DAY DCL DO ENDCASE ENDPROC EXCEPTION FLOOR GOTO HPSError IN INSTANCE LIKE MAP MIXED NEST NOWAIT OLD_TO_NEW_DATE FETCH HANDLER MODULE PTR SWITCH TRY WITH FLOAT HOLD NEW REDEFINE THROW TYPE EXCEPTION FOR INTO OBJECT REDEFINES TRACE VIA Table A-4 AND BY CEIL CLOSELOG CONTINUE DAY_OF_WEEK DEC DOUBLE ENDDCL ENDSQL EXTERN FOR HIGH_VALUES HPSErrorMessage INDEX INT LOC MILSECS MOD NEW_TO_OLD_DATE OBJECT AppBuilder 2. Table A-4 Reserved words for C OPENLOG PERFORM PRINT REDEFINE RGB RULE SET SMALLINT STARTTIME SUBHEADER THROW TRACE TRY VARCHAR VOID OR PIC PRINTER REDEFINES ROLLBACK SECONDS SETDISPLAY SQL STRING SUBSTR TIME TRANSACTION TYPE VERIFY WHILE OTHER POINTER PROC REPORT ROUND SECONDS_OF_DAY SETENCODING START STRLEN SWITCH TIMESTAMP TRUE UPPER VIA WINDOW OLD_TO_NEW_TIME OVERLAY PRAGMA PTR RETURN RTRIM SECTION SIZEOF STARTINTERVAL STRPOS TERMINAL TO TRUNC USE VIEW YEAR Table A-5 BREAK DOUBLE FLOAT OBJET STRING TRUE VOID Table A-6 BREAK DOUBLE FLOAT OBJET STRING TRUE VOID Keywords for C that can be disabled with PRAGMA KEYWORD CATCH ENDTRY FOR PTR SWITCH TRY CLASS EXCEPTION GOTO REDIFNE THROW TYPE CONTINUE FALSE MODULE REDEFINES TRACE VIA Keywords for C that can be disabled with -YK CATCH ENDTRY FOR PTR SWITCH TRY CLASS EXCEPTION GOTO REDIFNE THROW TYPE CONTINUE FALSE MODULE REDEFINES TRACE VIA Table A-7 ADDR BREAK CATCH CLEAR CONTAINS Reserved words for ClassicCOBOL AND BY CEIL CLOSELOG CONTINUE ASIS CASE CHAR COMMIT CONVERSE BASED CASEOF CLASS COMPONENT CURSOR A-4 Reserved Words . 1.Table A-7 DATE DBCS DETACH ELSE ENDDO ENDTRY Reserved words for ClassicCOBOL DAY DCL DIV END ENDIF EVENT FLOOR GOTO IN INSTANCE LIKE MAP MIXED NEST NOWAIT OLD_TO_NEW_DATE OTHER POINTER PROC REPORT RTRIM SECTION SIZEOF STARTINTERVAL STRPOS TERMINAL TO TRUNC USE VIEW YEAR DAY_OF_WEEK DEC DO ENDCASE ENDPROC EXCEPTION FOR HIGH_VALUES INDEX INT LOC MILSECS MOD NEW_TO_OLD_DATE OBJECT OLD_TO_NEW_TIME OVERLAY PRAGMA PTR RETURN RULE SET SMALLINT STARTTIME SUBHEADER THROW TRACE TRY VARCHAR VOID DAY_OF_YEAR DECLARE DOUBLE ENDDCL ENDSQL EXTERN FRACTION HOURS INIT INTEGER LOW_VALUES MINUTES MODULE NEW_TO_OLD_TIME OCCURS OPENLOG PERFORM PRINT REDEFINE ROLLBACK SECONDS SETDISPLAY SQL STRING SUBSTR TIME TRANSACTION TYPE VERIFY WHILE FALSEFLOAT FROM IF INSET ISCLEAR LOWER MINUTES_OF_DAY MONTH NOT OF OR PIC PRINTER REDEFINES ROUND SECONDS_OF_DAY SETENCODING START STRLEN SWITCH TIMESTAMP TRUE UPPER VIA WINDOW Table A-8 BREAK CURSOR Keywords for ClassicCOBOL that can be disabled with PRAGMA KEYWORD CATCH DECLARE FALSE MODULE REDEFINES THROW VIA CLASS DOUBLE FLOAT OBJECT SET TRUE VOID CONTINUE ENDTRY FOR PTR STRING TRY EXCEPTION GOTO REDEFINE SWITCH TYPE AppBuilder 2.1 Rules Language Reference Guide A-5 . Table A-9 BREAK CURSOR Keywords for ClassicCOBOL that can be disabled with -YK CATCH DECLARE FALSE MODULE REDEFINES THROW VIA CLASS DOUBLE FLOAT OBJECT SET TRUE VOID CONTINUE ENDTRY FOR PTR STRING TRY EXCEPTION GOTO REDEFINE SWITCH TYPE Table A-10 Reserved words for OpenCOBOL ADDR BREAK CATCH CLEAR CONTAINS DAY DCL DO ENDCASE ENDPROC EXCEPTION FLOOR GOTO IN INSTANCE LIKE MAP MIXED NEST NOWAIT OLD_TO_NEW_DATE OTHER POINTER PROC REPORT RULE SET SMALLINT STARTTIME SUBHEADER THROW TRACE AND BY CEIL CLOSELOG CONTINUE DAY_OF_WEEK DEC DOUBLE ENDDCL ENDSQL EXTERN FOR HIGH_VALUES INDEX INT LOC MILSECS MOD NEW_TO_OLD_DATE OBJECT OLD_TO_NEW_TIME OVERLAY PRAGMA PTR ROLLBACK SECONDS SETDISPLAY SQL STRING SUBSTR TIME TRANSACTION ASIS CASE CHAR COMMIT CONVERSE DAY_OF_YEAR DETACH ELSE ENDDO ENDTRY FALSE FRACTION HOURS INIT INTEGER LOW_VALUES MINUTES MODULE NEW_TO_OLD_TIME OCCURES OPENLOG PERFORM PRINT REDEFINE ROUND SECONDS_OF_DAY SETENCODING START STRLEN SWITCH TIMESTAMP TRUE BASED CASEOF CLASS COMPONENT DATE DBCS DIV END ENDIF EVENT FLOAT FROM IF INSET ISCLEAR LOWER MINUTES_OF_DAY MONTH NOT OF OR PIC PINTER REDEFINES RTRIM SECTION SIZEOF STARTINTERVAL STRPOS TERMINAL TO TRUNC A-6 Reserved Words . 1 Rules Language Reference Guide A-7 .Table A-10 Reserved words for OpenCOBOL TRY VARCHAR VOID TYPE VERIFY WHILE UPPER VIA WINDOW USE VIEW YEAR Table A-11 Keywords for OpenCOBOL that can be disabled with PRAGMA KEYWORD BREAK DOUBLE FALSE OBJECT SET TRUE VOID CATCH ENDTRY FOR PTR STRING TRY CLASS EXCEPTION GOTO REDEFINE SWITCH TYPE CONTINUE FLOAT MODULE REDEFINES THROW VIA Table A-12 Keywords for OpenCOBOL that can be disabled with -YK BREAK DOUBLE FLOAT OBJECT STRING TRUE VOID CATCH ENDTRY FOR PTR SWITCH TRY CLASS EXCEPTION GOTO REDEFINE THROW TYPE CONTINUE FALSE MODULE REDEFINES TRACE VIA AppBuilder 2.1. A-8 Reserved Words . • \Compatible Arithmetic—arithmetic that uses two sets of arithmetic functions. AppBuilder has three different arithmetic implementations: • Calculator Arithmetic—decimal arithmetic introduced in Seer*HPS 5. C does not support operations with long DECIMAL values.1. Restrictions in ClassicCOBOL. but they cannot always be used.2.0 for the server). Operator precedence and parentheses control the order of the operations. Native Versus Run-time Support Calculations Calculation of arithmetic expressions during rule execution can be performed using target language (C or COBOL) arithmetic operations or using routines included in run-time support libraries. To provide support for these variations. and so on.1. AppBuilder 2.1 Rules Language Reference Guide B-1 . such as binary and unary operations.4. This arithmetic is not supported on the mainframe platform. and Restrictions in OpenCOBOL for arithmetic support platform specifics. These two methods are referred to as native and run-time support calculations.4.1 Rules Language Reference Guide In previous versions of the product (Seer*HPS versions 5.4. • COBOL Arithmetic—decimal arithmetic introduced and implemented in Seer*HPS 5. These implementations can produce different results when calculating an expression.3. Native calculations are somewhat faster. Each operation produces an intermediate result (IR). For example.1 that conforms to COBOL rules for calculating the precision of intermediate results.4.0 and implemented in AppBuilder.0 for the workstation and 5. Also included are details on: • Native Versus Run-time Support Calculations • Platform Support • Implementation of DIV and MOD • Mapping to and from Numeric Data Items • Overflow Returned The evaluation of every formula is divided into the sequence of basic operations. 5.CHAPTER B DECIMAL ARITHMETIC SUPPORT AppBuilder 2. there are implementations of run-time arithmetic support. standard and user-defined function calls. one for constant expression evaluation and another for run-time calculations. Note See Restrictions in C. Restrictions in Java. 5.2. all arithmetic modes are fully supported and implemented.INI initialization file. ROUND. B-2 Decimal Arithmetic Support . If the result has more than 63 digits. Arithmetic mode is switched by the DECIMAL_ARITHMETIC_MODE parameter in the AP <platform> section of the HPS. PC Platform On a PC platform. Calculator arithmetic provides intermediate result precision to 63 (sixty-three) decimal digits independent of the precision of the operands involved.for calculator arithmetic • COBOL . Platform Support Different types of arithmetic are supported on the PC Platform and Mainframe Platform. or TRUNC. Refer to Error Handling for important issues about differences in the error handling during native calculations.for COBOL arithmetic • COMPATIBILITY .for original-compatible arithmetic Mainframe Platform COBOL arithmetic mode is the only fully-supported arithmetic on the mainframe. you can choose to perform constant folding using any of the three described arithmetic modes: calculator. However. or original-compatible. • Local procedures or object methods returning non-native types are not used. COBOL. it is truncated using the rules explained below. This parameter can have the following values: • CALCULATOR . INSET. • There are no division (/). then native calculations are used: • All the operands in the expression and destination field (if present) are of native type (The set of native types is different for each implementation of run-time arithmetic support. DIV. or MOD operations in the expression.Platform Support If all of the following conditions are true for an expression in the rule. FLOOR. exponentiation (**). Calculator Arithmetic The primary difference between calculator and COBOL arithmetic are the rules for calculating intermediate result precision.) • The expression does not contain the mathematical functions CEIL. In case 2 the result of first multiplication is 10**(-60). AppBuilder 2. run-time procedures are used instead and performance is sacrificed for increased precision when using calculator rules on the mainframe. if the fractional part is truncated only a warning message is generated. As remaining digits are zeroes. Calculator arithmetic does not use native COBOL arithmetic for DECIMAL data type at all. • If I <= 63.31). then I+D-63 digits of the fractional part is truncated. however. Here I = 0. Constant Expressions in Calculator Arithmetic Constant expressions are computed during compile time. D3131. and the result of the second one must be 10**(-90). Native Types in Calculator Arithmetic Native types in calculator arithmetic are INTEGER and SMALLINT on all platforms. you receive an error message if an overflow occurs during these computations. For example. When the integer part of the result has more than 31 digits: • A warning message is issued if the constant expression is a part of an arithmetic formula containing non-constant operands • An error message is issued if. so 90 – 63 = 27 digits are truncated. D3131A DEC(31. then if I+D >63. and D = 90. assume that the intermediate result of an arithmetic operation has I integer and D fractional places: • If I > 63. there are only numeric literals and the whole expression can be calculated during compile time. but I = 90 > 63. so an overflow occurs. when the integer part is truncated. for example.Calculator Arithmetic For example. consider the following Rules code: DCL D3100.1 Rules Language Reference Guide B-3 . In any case. and the result of the second one must be 10**90. an error message is issued.1. the result is zero. D3100A DEC(31). then an overflow error occurs. ENDDCL *> case 1 <* MAP 10**30 TO D3100 MAP D3100*D3100*D3100 TO D3100A *> Case 1: Overflow <* *> case 2 <* MAP 10**(-30) TO D3131 MAP D3131*D3131*D3131 TO D3131A *> Case 2: D3131A = 0 <* RETURN In case 1 the result of first multiplication is 10**60. it is not possible to detect whether an overflow has occurred.dmax) Note Operation MOD is implemented as a composition of 3 operations: op1 .COBOL Arithmetic COBOL Arithmetic COBOL arithmetic support includes these topics: • Native Types in COBOL Arithmetic • DMAX Parameter • Truncation Rules for Intermediate Result • Length and Scale of Function Results • Overflow Conditions • Constant Expressions in COBOL Arithmetic Intermediate result precision in the COBOL arithmetic rules depends on the precision of the operands and the precision of the destination field. Then.d2) Max(d1.(op1 div op2 ) * op2 Native Types in COBOL Arithmetic Native types in COBOL arithmetic are listed in the following table: PC platform MainFrame platform INTEGER or SMALLINT INTEGER. whichever is greater i1 + i2 i1 + d2 i1 + d2 i1+i2+d2+1 63 – dr See “Length and Scale of Function Results”. whichever is greater d1 + d2 Dmax 0 Max(d1. the intermediate result has the number of the integer and decimal places (ir and dr. SMALLINT and DEC or PIC values with length less than EPT. Table B-1 Operation + or * / DIV MOD ** Math functions COBOL Arithmetic Intermediate Results Integer Places (i1 or i2) + 1. Assume that the operands of the binary operation have i1 or i2 integer places and d1or d2 decimal places.d2. B-4 Decimal Arithmetic Support . respectively) as shown in Table B-1. respectively. If native C or COBOL arithmetic is used. Decimal Places d1 or d2. For integer variables. constants. To determine this. DIV and MOD operations in the expression Table B-2 indicates when intermediate results might get truncated (if an expression requires extended precision then / is equal to 63. The result scale (see “Length and Scale of Function Results”).COBOL Arithmetic DMAX Parameter dmax is a precision parameter that is defined for the expression according to the rules outlined below. The operand of an expression can be: data fields. INTEGER. or TRUNC. all subexpressions of the MAP statement source have the same dmax. For example. Note that dmax is calculated for an expression “as a whole”. INSET. Truncation Rules for Intermediate Result Truncation rules for intermediate result in COBOL arithmetic depend on whether the expression requires extended precision. EPT default value is 15. otherwise N is equal to 30): Table B-2 Intermediate Result Truncation Rules Value of d Any value Value of i + dmax Any value Action taken I integer and d decimal places are carried Value of i + d <=N AppBuilder 2. exponentiation (**). dmax for the expression is calculated as the maximum of scales of operands (as defined below) and the scale of the target of an expression (the target of a MAP statement or procedure parameter).1 Rules Language Reference Guide B-5 . The scale for these operands is: Data fields Constants User procedures Standard functions The scale of the data field. The scale of the return value from procedure declaration. • The expression does not contain the mathematical functions CEIL. ROUND. • Local procedures or object methods returning decimals longer than extended precision threshold are not used. it is 0 (zero).1. and standard functions. FLOOR. the extended precision threshold (EPT) is used. Expression does not require extended precision if all the following conditions are met: • All the operands of the expression and result field are SMALLINT. • There are no division (/). The extended precision threshold can be set using rule preparation parameter -K<value>. dmax is calculated separately (independent of the enclosing expression) for: • The source of the MAP statement • Arguments to user procedure calls (even if used inside an expression) • Arguments to standard non-math functions Arguments of standard math functions (ROUND. user procedure calls. TRUNC. or decimals having no more than extended precision threshold decimal places. CEIL and FLOOR) are processed as follows: the first argument is considered a subexpression of the enclosing expression and dmax for the second argument is calculated separately. The scale of the constant (number of significant digits after decimal point). In the second case.COBOL Arithmetic Table B-2 Intermediate Result Truncation Rules Value of d <=dmax >dmax Value of i + dmax Any value <=N >N Action taken N-d integer and d decimal places are carried I integer and N-i decimal places are carried N-dmax integer and dmax decimal places are carried Value of i + d >N Length and Scale of Function Results Rules Language supports four mathematical functions that allow you to mathematically modify an expression : • CEIL • ROUND • TRUNC • FLOOR These functions use one or two parameters: • The value to be modified • The significant number of digits to which the function applies This is a positive value referring to the digits to the right of the decimal point . where the second operand of a math function is a variable: i = N-d1 d = d1 (See Table B-2 for the definition of N. Here i. where the second operand of a math function is a constant with value C (or a constant expression giving integer result C): If C <= 0 then i = max(i1. d = min(d1.|C|). they can be predicted with reasonable accuracy.) In the second case. the second argument of the math function is a variable or an expression. respectively.zero referring to the digit to the immediate left of the decimal point and a negative value referring to digits farther to the left of the decimal point. Consider these two important cases. i1 and d1 denote integer and decimal places for the result and the first operand of the math function. d. In the first case. B-6 Decimal Arithmetic Support . In the first case. The data type of the returned value for any of these functions is DEC.|C|) The values of i and d are used in the calculations of dmax and for the calculations of length and scale of operands in compound expressions. the second argument is a constant or constant expression. In the first case. Refer to “Functions” for detailed descriptions and examples of the mathematical functions used in Rules Language. the length and the scale of the result cannot be accurately predicted during preparation time. In the second case. d=0 If C > 0 then i=i1. 1050.Overflow Conditions The following example clarifies the concepts described in Overflow Conditions (in this example. • If the destination field has fewer decimal places for the fractional part than the intermediate result has. EPT=15). only a warning message is generated. ENDDCL MAP 10**14 TO D1500 MAP D1500*D1500*D1500 TO D1500A *> Overflow (result of operation has too long integer part <* MAP D1500 TO D1510 *> Overflow (integer part of source in longer than that of a target <* MAP –50 TO I MAP ROUND(D1500. D1510. An error message is generated if: • Division by zero occurs during these computations • The integer part is truncated However. Overflow Conditions Since all values of i and d are calculated at compile time. Example .1.10). then the fractional part is truncated according to the rules in Table B-2 and no error code is set. an overflow error occurs. and an overflow situation occurs if the second operand is less than -31. AppBuilder 2. D1510A DEC(15. • If the destination field has fewer decimal positions for the integer part than for the intermediate result.1 Rules Language Reference Guide B-7 . then its value is truncated according the destination data type. DCL D1500. I INTEGER. if the fractional part is truncated. D1500A DEC(15). is too long) <* Constant Expressions in COBOL Arithmetic Constant expressions are computed during compile time.I) TO D1500A *> No overflow – 0 is a correct result <* MAP CEIL(D1500. • If the result of the operation is assigned to any field. an overflow error occurs. the following can occur: • If the actual result of computations has an integer part longer than intermediate results precision calculated according to rules described in Table B-1.COBOL Arithmetic Note that an error is reported at compile time if C < -31.I) TO D1500A *> Overflow (result of math function. • otherwise. Table B-3 Compatible Arithmetic Intermediate REsults I Max(i1. • i2. s2 are the length and the scale of the second operand. for example. Intermediate result is calculated in two steps: 1.q_max) s1*|n| Dmax max(s1. Q_max is calculated according to the following rules: • if an expression is a source of a MAP statement. 31 if n is odd Operations +/* / ** Note 2. there are only numeric constants in the expression.q_max) max(s1. S are the length and the scale of the intermediate result. Run-Time Calculations The original arithmetic uses the value q_max to calculate precision of the intermediate results. dmax and maxlen are calculated. s1 are the length and the scale of the first operand. truncation of the intermediate result is performed according to the following rules: • If s <= dmax then i is set to maxlen – s • Else if i + dmax < maxlen then s is set to maxlen – i B-8 Decimal Arithmetic Support . q_max is equal to the scale of destination.s2. Length and scale of an intermediate result. q_max is equal to 0. • i1.s2) s1+s2 max(s1. In Table B-3: • I.q_max) max(s1.i2)+1 i1+i2 i1+s2 i1*|n| S max(s1. If n is negative then a**n is calculated as 1 / a** (-n) Intermediate result is truncated. • if an expression is a part of the condition and the other operand of the condition is a constant or a variable. the whole expression can be calculated during compile time. then q_max is equal to its scale.q_max) Maxlen 64 64 64 32 if n is even. If i+s > maxlen. • An error message is returned if.q_max) max(s1.\Compatible Arithmetic When the integer part of the result has more than 31 digits: • A warning message is returned if the constant expression is a part of an arithmetic formula containing non-constant operands. \Compatible Arithmetic AppBuilder uses two sets of arithmetic functions—one for Run-Time Calculations and one for Constant Expression Evaluation in Compatible Arithmetic. that is. See also Division by Zero.s2. • n is the second operand of exponentiation. The operations ** and MOD are never folded. the expression is considered to require extended precision.1. AppBuilder 2. with the following exceptions: 1. Therefore.1 Rules Language Reference Guide B-9 . since q_max parameter is not used. To determine whether an expression requires extended precision. FLOOR and TRUNC • Extended precision is not required for calculating an expression Division operator is handled by different rules. rules for constant folding on the mainframe are generally similar to those on the PC platform.\Compatible Arithmetic • Else i is set to maxlen . constant arithmetic computation results may differ from those of original-compatible calculations.PC • Constant Expression Using Compatible Arithmetic . a parameter of a standard function. The constant folding is performed using native C language type double via C standard library functions.Mainframe In original-compatible arithmetic. See “Division by Zero” for more details. Note This is done at runtime and these values are NOT known statically. Subscripts are never folded.PC Constant folding on the PC platform occurs only if the following conditions are satisfied: • An expression is a source of a MAP statement. Constant Expression Evaluation in Compatible Arithmetic • Constant Expressions Using Compatible Arithmetic . If the result is greater than 10**EPT. In case when an expression is not a source of MAP statement. If the length of the target of a MAP statement is longer than EPT digits. or a variable subscript. The default value of extended precision threshold is 15. its value is calculated according to the rules described in the next section. “Truncation rules for intermediate result”).dmax and s is set to dmax. a FROM clause index. Constant Expression Using Compatible Arithmetic . An operation requires extended precision if any of the operands require extended precision. The results of original-compatible computations may differ from those of calculator arithmetic in the 15th digit after the decimal point. A constant requires extended precision if its length is greater than EPT (see “COBOL arithmetic”. Use the following rules to determine whether an expression requires extended precision: 1. its target is considered to be integer variable • All operands are constants in the whole expression (with the exception of 0**expr and expr**0 – these expressions are always treated as constants 0 and 1 respectively) • An expression does not contain CEIL. 2. an expression is considered to require extended precision.Mainframe Constant Expressions Using Compatible Arithmetic . 2. Results upon division by zero that occur during rule execution in all arithmetic modes are described in: • Division by Zero Using Compatible Arithmetic . the result of the operation is overflow and HPSError does not change Division by Zero Using Compatible Arithmetic . but 1 MOD 2 in MAP ROUND(D1510. rule execution abends (stops with system error) in both native and run-time support calculations. B-10 Decimal Arithmetic Support . If D0_CHECK equals YES (all upper case. then rule execution stops with a system error. during a rule preparation in original-compatible arithmetic. If the first argument of ROUND does not require extended precision. no blanks allowed).Mainframe Only COBOL arithmetic is implemented on the mainframe platform. the result of the operation is overflow and HPSError is set • in original-compatible arithmetic. 1+2) TO D1610 is computed at compile time (if ETP >= 15).INI. rule execution stops with a system error in all three arithmetic modes. 1 MOD 2) TO D1610 is not computed at compile time.\Compatible Arithmetic 3. Division by Zero If. then the attempt to calculate the divisor is made regardless of rules described above. a division (/ or DIV) is encountered in any expression.PC • Division by Zero Using Compatible Arithmetic . Otherwise: • in calculator and COBOL arithmetic.Mainframe Division by Zero Using Compatible Arithmetic .PC If division by zero occurs in native calculations. behavior is triggered by D0_CHECK key of [AE Runtime] section of HPS. In case of division by zero. In run-time support calculations. regardless of first argument being or not being constant. the second argument is treated as a separate expression and folded (if it can be folded) in the same way as a source of MAP into INTEGER. Thus 1+2 in MAP ROUND(D1510. The divisor is calculated if it does not contain any variables and there are no extended precision operands in expression. DIV is implemented as follows: to calculate A div B. AppBuilder 2.PC and Overflow Error produce system errors.PC Table B-4 Division-by-Zero Error Results On a PC you receive: HpsError is set to the corresponding error code and the rule continues executing.INI [AE Runtime] section OVERFLOW_CHECK key. No error code is set. both Division-by-Zero Error . Any operation with DEC overflow value results in overflow value. Division-by-zero and overflow run-time errors on the PC workstation platform are described in Table B-4 and Table B-5. however. this is not true for an INTEGER and SMALLINT overflow value. Overflow is a result of: Run-time arithmetic calculation Native expression You can change this default result for the overflow in a run-time arithmetic calculation exception using the HPS. an error message is issued as a result of the rule preparation. On the mainframe platform. Note There is no way to stop rule execution and report an error if native expression was generated. The result of computation is overflow value C run-time error Zero is a result of: Run-time arithmetic calculation Native expression You can change this default result for the division-by-zero in a run-time arithmetic calculation exception using D0_CHECK key of [AE Runtime] section of HPS. Division-by-Zero Error . DIV or / operations is equal to zero. Implementation of DIV and MOD AppBuilder supports DIV and MOD operations with non-integer operands. The overflow value is either DEC or PIC value filled with symbol ‘*’ (length is equal to the length of the variable) or INTEGER or SMALLINT value equal to 0. If this key is set to YES (all capital letters) then the rule execution is stopped with the system exception. the rule execution stops with the system exception Division-by-zero anytime the divisor in MOD.Error Handling Error Handling If an error occurs during a constant expression calculation. Rule continues executing. If the D0_CHECK key is set to YES (all capital letters).1. A / B is calculated and all digits after decimal point are truncated. In original-compatible and calculator arithmetic.1 Rules Language Reference Guide B-11 .INI. The result of operation is unpredictable. The result of computation is an overflow value. Overflow Error Table B-5 Overflow Error Results On a PC you receive: HpsError is set to the corresponding error code and the rule continues executing. B-12 Decimal Arithmetic Support . an overflow value is assigned to that data item.11 DIV 0.Mapping to and from Numeric Data Items In original-compatible and calculator arithmetic.2 TO X *> *> *> *> *> *> *> *> X X X X X X X X = = = = = = = = 5 55 5 0 1 0 0. a warning is issued if its integer part is greater than 10 or 5. Example .as in original-compatible run-time and calculator arithmetic. DIV is implemented as a division with scale of a result equal to 0 and MOD .11 <* <* <* <* <* <* <* <* Mapping to and from Numeric Data Items Different numeric data items have a different range of values. If the MAP target is not a native type variable. Specifically.1 MOD 0. On a workstation. the value assigned cannot be predicted.2 TO X 0. if the MAP target is a native type variable. therefore.11 MOD 0. Results of computations are the same for all these implementations. the value assigned to INTEGER or SMALLINT variable cannot be predicted. respectively.2 TO X 0.2 TO X 11 MOD 2 TO X 11 MOD 0. However.2 TO X 1.DIV and MOD implementation MAP MAP MAP MAP MAP MAP MAP MAP 11 DIV 2 TO X 11 DIV 0. If a variable is assigned to an INTEGER or SMALLINT variable. execution is terminated with a system error. on the mainframe platform.1 DIV 0. MOD is implemented as follows: A mod B = A .B * (A div B) In COBOL arithmetic.1 0. overflows can occur during mappings to numeric data items. Situations when error and warning messages are issued at compile time in processing MAP statements to and from these numeric data items are described in: • INTEGER and SMALLINT • DEC and PIC • Expressions INTEGER and SMALLINT If a constant is assigned to an INTEGER or SMALLINT variable.2 TO X 1. no checking for overflows is performed. the error about overflow or a warning about truncation is issued accordingly. DEC and PIC If a constant with decimal part present is assigned to the DEC or PIC variable that does not fit. Example . D0201 DEC(2. a warning is issued.1. Expressions If an expression is assigned to numeric data item.2 (q_max = 1. thus no digits after decimal point are kept) 1. D1001 DEC(10.Overflow Returned If an integer constant is assigned to a DEC or PIC variable that does not fit. providing more accurate result) 1 (same arithmetic functions used for constant and run-time computations) 1 AppBuilder 2. but dmax=1 for division) *> case D <* *> case E <* COBOL 0 1. one digit is kept) 1 (constant computations – four C doubles are added together) 1 (q_max=0.1 Rules Language Reference Guide B-13 . ENDDCL MAP 1 TO I MAP I/3+I/3+I/3+I/3 TO D1000 MAP I/3+I/3+I/3+I/3 TO D1001 MAP1/3+1/3+1/3+1/3 TO D1000 *> case A <* *> case B <* *> case C <* MAP 1 TO D0201 MAP D0201/3+ D0201/3+ D0201/3+ D0201/3 TO D1000 MAP D0201/3+ D0201/3+ D0201/3+ D0201/3 TO D1001 RETURN Results (values MAPped in destinations) are described in Table B-6. In original-compatible run-time. If a variable is assigned to a DEC or PIC variable that does not fit. math functions return overflow only if a result’s decimal part is longer than 63 digits.3 (all 63 digits are still calculated. the error is issued only if the constant absolute value is greater than or equals 2**32.1). D1000 DEC(10).1).2 0 1 1. Overflow Returned In calculator and COBOL arithmetic.Overflow Return Function Consider the following example: DCL I INTEGER. no checking for overflows is performed. Table B-6 Overflow Return Results Calculator 1 (all 63 digits are calculated) Original-Compatible A B C D 0 (q_max = 0. arithmetic math functions return 0 for variables and overflow result for constants if an overflow situation occurs. 2 Original-Compatible E 1.2 B-14 Decimal Arithmetic Support .Overflow Returned Table B-6 Overflow Return Results Calculator 1.3 COBOL 1. Index INDEX AppBuilder 2. 13-15 character comparing values 4-14 mapping values 2-7 Character data type data type character 2-11 i . <emphasis 2>see operators Array methods Append 2-10 Delete 2-11 Elem 2-10 Insert 2-11 Size 2-10 Array Object specifications 2-8 assigning new data to a view 9-1 assigning Object data type variables 9-1 assignment statements 9-1 CLEAR 9-11 definition 9-1 OVERLAY 9-12 C C mode date default format string 5-10.1 Rules Language Reference Guide .1.(subtraction) 4-6 B backslash 3-9 Boolean condition definition 4-13 BOOLEAN data type 2-2 Boolean operator AND 4-13 NOT 4-13 OR 4-13 Boolean type converting Java values in ObjectSpeak 13-14 building a local view using VIEW CONTAINS clause 6-4 Symbols * (multiplication) 4-7 ** (exponentiation) 4-7 *> (end comment) 8-2 + (addition) 4-6 ++ (concatenation) 5-22 / (division) 4-7 <* (begin comment) 8-2 A addition operator 4-6 aggregates using in MAP statements 9-4 alias definition 3-14 purpose for declaring 3-15 aliases declaring for Window objects in C 13-2. 5-11 calculations arithmetic native vs. run-time support B-1 run-time B-8 calculator arithmetic B-2 native types in B-3 CASE clause 10-3 CASE OTHER clause 10-3 CASE statement symbol in 3-12 CASEOF statement 10-2 CEIL (ceiling) function 5-3 CHAR fields in conditions 4-15 fields in MAP statements 9-5 function 5-9 CHAR function symbols 5-20 CHAR string function 5-20. 13-10 Object data item 3-14 arithmetic implementations B-1 arithmetic operators. 13-24 variable 3-1 data items Aliases 3-14 constants 3-1 expressions and conditions 4-1 locally-declared CHAR and VARCHAR 2-14 ii .character data type CHAR 2-12 character literals 3-8. 13-38 CONVERSE WINDOW NOWAIT 11-13 conversion functions DATE 5-10 DAY 5-9 DAY_OF_WEEK 5-9 DAY_OF_YEAR 5-9 HOURS 5-10 INT 5-11 MINUTES 5-10 MINUTES_OF_DAY 5-10 MONTH 5-9 NEW_TO_OLD_DATE 5-11 NEW_TO_OLD_TIME 5-11 OLD_TO_NEW_DATE 5-12 OLD_TO_NEW_TIME 5-12 SECONDS 5-9 SECONDS_OF_DAY 5-10 TIME 5-11 YEAR 5-9 D data item character literals 3-8 classification 3-1 definition 3-1 initialization 3-13 numeric 3-11 Object 3-14. 3-9 character string including single quotes in 3-8 character string functions 5-17 character value data item 3-8 CICS execution environment 11-8 rule initiation 11-8 clause LISTENER 6-8 sets using IN clause 3-12 using VIEW CONTAINS 6-4 CLEAR statements 9-11 COBOL generating copybooks 13-50 maximum length of names 13-50 setting _LEN variable 13-41 COBOL arithmetic B-4 mainframe support B-2 comment statements 8-2 samples 8-2 single line 8-2 COMMIT TRANSACTION file access statements 8-9 common procedure examples 7-2 comparisons 4-14 identifying illegal 4-14 views 4-15 compatible arithmetic B-8 compiler pragmatic statements 8-10 concatenation(++) string function 4-3 condition statements definition 10-1 conditions CHAR fields in 4-15 definition 4-9 illegal comparison of 4-14 INTEGER fields in 4-15 PIC fields in 4-15 SMALLINT fields in 4-15 configuration options setting case-sensitivity 12-14 connection pool clients and database 13-22 constant expression compatible arithmetic using mainframe B-9 constant expressions compatible arithmetic for PC B-9 constants data items 3-1 decimal 3-11 control statements 8-1 CONVERSE REPORT special considerations 11-14 CONVERSE REPORT statement 11-13. 13-24 defining specific events 7-6 DETACH USE RULE statements 11-5 Index iii .data type Array Object 2-8 BOOLEAN 2-2 CHAR 2-12 DATE 2-6 date and time 2-5 date and time formats 2-5 DBCS.TIME 5-11 Default Object data item 3-14.DATE 5-10 default format string . MIXED 2-13. 13-8 DEC 2-4 double-byte character 2-13 fixed length 2-12 IMAGE 2-7 INTEGER 2-3 large object 2-6 large object file name 2-6 mapping character values 2-7 mapping errors 9-4 MIXED 2-14 numeric 2-2 OBJECT 2-8 Object Pointer 13-11 PIC 2-3 Rules Language support 2-1 setting VARCHAR length 13-3 single-byte character 2-13 SIZEOF function sizes 5-26 SMALLINT 2-3 TEXT 2-7 TIMESTAMP 2-6 VARCHAR 2-13 variable length 2-13 data types in a variable declaration 6-3 NULL 13-24 database access 8-4 DATE conversion function 5-10 data type 2-6 fields in MAP statements 9-5 list of format string tokens 5-14 DATE and TIME expression 4-5 format strings 5-12 using mixed operands 4-5 Date and Time common separators 5-13 function definitions 5-7 functions 5-5 sample functions 5-15 date and time converting variables 2-6 data type 2-5 locally-declared 2-6 supported formats 2-5 date and time type converting Java values in ObjectSpeak 13-14 DATE format string default 5-10 DATE function 5-8 DAY conversion function 5-9 DAY function 5-7 DAY_OF_WEEK conversion function 5-9 DAY_OF_WEEK function 5-7 DAY_OF_YEAR conversion function 5-9 DAY_OF_YEAR function 5-7 DBCS character set functions 5-21 character values 4-14 data types 2-13 fields in MAP statements 9-8 fields in OVERLAY statements 9-16 illegal comparisons 4-14 in DATE function 5-8 initial values for data types 3-14 literals 3-9 operands of concatenation 4-3 SETENCODING 5-28 string type 13-13 using data types 5-22 DBCS and MIXED 13-9 DBCS or MIXED field mapping to or from 9-8 DCL declarative statements 6-1 local procedure in 6-4 preparing 6-12 DDL using Initialization to specify decimal fields 13-40 DEC length and scale of field 2-4 DEC and PIC mapping B-12 DEC field mapping to 9-6 DECIMAL constants 3-11 data type 2-4 fields in MAP statements 9-5 declaring variables 6-2 DECR(decrement) function 5-5 default format string . DIV arithmetic operator 4-7 DIV and MOD implementation B-11 division by zero using compatible arithmetic B-10 division operator 4-7 division-by-zero error for PC B-11 DMAX parameter B-5 dot symbol to qualify fields 3-4 double-byte character data types 2-13 double-quote literals 3-9 E ELSE clause 10-1 END in CONVERSE REPORT statements 11-14 ENDIF clause 10-1 ENDPROC in defining procedures 7-1 entities with equal names 6-8 entity precedence order 6-8 error code processing sample 7-3 error handling during constant expression calculation B-11 error-handling functions 5-24 errors in data type maps 9-4 escape sequences 3-9 list of supported 3-10 event defining parameters of objects 7-6 handling of object types 7-6 setting parameters 7-6 event handler statement 13-35 event handling procedure 7-4 event naming conflicts 6-8 event parameters 7-6 event procedure for multiple events 6-7 for multiple object types 6-7 for multiple objects 6-7 using in a rule 7-5 event procedure declaration 6-6 events global 11-15 execution environments 11-10 exponentiation 4-7 expression 4-4 character 4-2 comparing PIC fields to 4-13 conditions 4-9 constant evaluation in compatible arithmetic B-9 definition 4-1 numeric 4-3 operators 4-6 unary minus 4-4 using ObjectSpeak to reference properties 4-17 expressions conditions B-5 constant in calculator arithmetic B-3 mapping B-13 ObjectSpeak 4-16 F fields comparing with expressions 4-13 in MAP statements 9-1 in OVERLAY statements 9-16 length limitations in mapping 9-6 qualifying 3-3 file access statements 8-4 fixed-length data types 2-12 FLOOR function 5-3 format string DATE 5-10 definition 5-12 list of separators 5-14 not supported in OpenCOBOL 5-12 time default format string 5-11 FRACTION function 5-8 FRACTION function 5-8 function results length and scale B-6 iv . 13-42 CLEARNULL 13-24 DATE 5-8 date and time 5-5 DAY 5-7 DAY_OF_WEEK 5-7 DAY_OF_YEAR 5-7 DERC (decrement) 5-5 double-byte character set 5-21 error handling 5-24 error message 5-25 FLOOR 5-3 FRACTION 5-8 GET_ROLLBACK_ONLY 13-26 HIGH_VALUES 5-27 HOURS 5-8 HPSError 5-24 INCR (increment) 5-4 INT 5-9 ISCLEAR 4-12 ISNULL 13-25 LOW_VALUES 5-27 mathematical 5-2 MILSECS 5-7 MINUTES 5-8 MINUTES_OF_DAY 5-8 MONTH 5-7 NEW_TO_OLD_DATE 5-9 NEW_TO_OLD_TIME 5-9 numeric conversion 5-2 OLD_TO_NEW_DATE 5-9 OLD_TO_NEW_TIME 5-9 Reset Error 5-25 ROUND 5-3 sample date and time code 5-15 SECONDS 5-7 SECONDS_OF_DAY 5-8 SET_ROLLBACK_ONLY 13-26 SETDISPLAY 5-28 SETENCODING 5-28 SIZEOF 5-26 support 5-25 TIMESTAMP 5-8 TRACE 5-29 TRUNC (truncate) 5-4 using CHAR.INI setting case-sensitivity 12-14 setting macro value validation 12-16 HPSID system identifier precedence 6-11 I identifiers case-sensitivity 2-8 IF statement 10-1 example 10-2 IMS execution environment 11-8 IMS Rule Processing Types 11-8 IN clause used for set names 3-12 INCR(increment) function 5-4 INIT statements USE RULE 11-7 initial values for data types 3-14 initialization automated processes 3-13 of variable data types 3-13 process 3-13 INSET operator 4-11 Boolean condition 4-12 order of operations 4-12 INT conversion function 5-11 INT function 5-9 INTEGER data type 2-3 field in conditions 4-15 in MAP statements 9-5 INTEGER and SMALLINT mapping B-12 integer division 4-7 intermediate result truncation rules B-5 invoking methods 8-3 Index v . MIXED AND DBCS 5-22 YEAR 5-7 G global eventing using CONVERSE to manage 11-15 global views initialization upon start 3-13 H hexadecimal literals 3-11 hexadecimal notation 3-10 HOURS conversion function 5-10 HOURS function 5-8 HPS.functions CEIL (ceiling) 5-3 CHAR 5-9 character string 5-17 character string descriptions 5-18. J Java changing the number of occurrences 13-27 CLEARNULL function 13-25 conversion from Rules Language 4-18. 13-13 creating an Alias for class import 13-31 data item variables 13-23 declaring aliases for identifiers 13-33 defining a local procedure using views 13-17 Dynamically-Set View Functions 13-26 event handler assignment 13-31 event handler restrictions 13-18 event procedures 7-5 GET_ROLLBACK_ONLY function 13-26 ISNULL function 13-25 LISTENER clause 6-8 NULL data items 13-24 SET_ROLLBACK_ONLY function 13-26 setting _LEN variable 13-8 specifying the event handler 13-34 transaction support 13-20 using Object Type data type 13-10 Java mode date default format string 5-10 default format string for TIME 5-11 L LIKE clause defining identical fields or views 6-3 subscripting with 6-3 literals concatenation 5-22 decimal length 3-11 double quote 3-9 integer length 3-11 single quote 3-9 supported numeric 3-11 local procedure declaration 6-4 LOWER() string function 5-18 M macro name validation 12-15 value validation 12-16 macro preprocessor case-sensitivity option 12-14 MacroDomains for macro value validation 12-16 macros definition 12-1 MAP Statements to identify arguments 3-5 MAP statements DBCS and MIXED fields 9-8 field combination matrix 9-5 fields 9-1 mapping views 9-10 multiply occurring views 9-3 restrictions on 9-4 VARCHAR fields 9-6 mapping a view to a view 9-10 mapping data examples 9-5 mathematical functions 5-2 methods HPS_EVENT_VIEW 7-6 invoking for objects 8-3 invoking nested 8-4 invoking using ObjectSpeak 8-3 MILSECS function 5-7 MINUTES conversion function 5-10 MINUTES function 5-8 MINUTES_OF_DAY conversion function 5-10 MINUTES_OF_DAY function 5-8 MIXED character set function 5-21 character values 4-14 concatenation 4-3 data types 2-13 DATE argument 5-8 fields in MAP statements 9-8 illegal comparisons 4-14 initial values for data types 3-14 Java values 13-9 literals 3-9 mapping to a field 9-8 operands 4-3 SETENCODING 5-28 MOD arithmetic operator 4-8 modifying an expression B-6 modulus operator 4-8 MONTH conversion function 5-9 MONTH function 5-7 multiple-occurring subviews variables 3-7 multiplication operator 4-7 multiply occurring views in MAP statements 9-3 in SQL statements 8-5 using OVERLAY statement 9-16 N naming conflicts 6-8 vi . 13-24 setting constructor parameters 13-13 object transferring from workstation to host 2-7 OBJECT data type 2-8 object data types 2-6 Object Method call setting parameters 4-16 Object Pointer specifications 13-11 OBJECT type converting Java values in ObjectSpeak 13-14 Object Type equivalency to Object Pointer 13-10 ObjectSpeak 4-16 conversion 4-18 occurrences setting the number of 6-14 occurring views in Java 13-26 Occurring Views functions APPEND 13-28 DELETE 13-29 INSERT 13-29 OCCURS 13-27 REPLACE 13-30 RESIZE 13-28 octal 3-10 octal notation 3-10 OF clause to qualify fields 3-3 OFF in CONVERSE REPORT statements 11-14 OLD_TO_NEW_DATE conversion function 5-12 OLD_TO_NEW_DATE function 5-9 OLD_TO_NEW_TIME conversion function 5-12 OLD_TO_NEW_TIME function 5-9 open source COBOL data type descriptions 13-49 OpenCOBOL Data Type Descriptions 13-49 generation facility features 1-4 setting VARCHAR length 13-49 operations order of 4-15 operators arithmetic 4-6 INSET 4-11 order of 4-4 precedence 4-9 relational and Boolean order 4-15 unary minus 4-4 order of operations 4-4 overflow returned B-13 overflow conditions B-7 overflow error compatible arithmetic B-11 Overflow Return function sample B-13 OVERLAY statements 9-12 P parameter types compatible for setting signatures 6-9 parameters DMAX B-5 setting event 7-6 PERFORM statement 11-17 Index vii .native types in COBOL arithmetic B-4 negative numbers in numeric literals 3-11 NEST statement statements NEST 11-5 nesting IF statements sample 10-2 NEW_TO_OLD_DATE conversion function 5-11 NEW_TO_OLD_DATE function 5-9 NEW_TO_OLD_TIME conversion function 5-11 NEW_TO_OLD_TIME function 5-9 notation hexadecimal 3-9. 3-10 octal 3-9 NULL variable data type value 13-24 null string 3-8 length 5-21 numeric data items mapping to and from B-12 numeric data type 2-2 DECIMAL 2-4 INTEGER 2-3 PIC 2-3 SMALLINT 2-3 numeric types converting Java values in ObjectSpeak 13-13 numeric value data item definition 3-11 O Object creating new instances 4-16 default data item 3-14. 13-52 Rule declaration preparation 6-12 sample local 6-12 rule preparation errors and warnings 9-4 rules execution environments 11-10 Rules component support 11-10 Rules Language identifier valid syntax 3-15 run-time arithmetic support B-1 S same-named fields mapping 9-10 same-typed fields mapping 9-11 SECONDS conversion function 5-9 SECONDS function 5-7 SECONDS_OF_DAY conversion function 5-10 SECONDS_OF_DAY function 5-8 SECTION in CONVERSE REPORT statements 11-14 separators common 5-13 SETENCODING function 5-28 signatures choosing and setting 6-9 comparison definitions 6-9 parameter types 6-9 setting 6-9 single-byte character data types 2-13 single-quote literals 3-9 SIZEOF platform-specific function values 5-26 SMALLINT data type 2-3 fields in conditions 4-15 in MAP statements 9-5 in VARCHAR variable 2-15 using _LEN variable 2-15 specifying the input view in a RULE call 11-2 Q qualification using with same names 6-9 qualifying fields partial 3-5 qualifying views in SQL code 8-5 R reference data type definition on workstation 2-6 host data type definition 2-6 relational condition 4-10 Report Communication Area(RPTCA) CONVERSE REPORT statements in 11-15 RETURN statements 11-16 viii . 13-42. 13-15.PIC data type 2-3 fields in conditions 4-15 in MAP statements 9-5 storage codes 2-3 PIC field mapping to or from 9-6 platform support B-2 platforms supported 1-4 POST EVENT statement 8-10 PRAGMA alias property 13-33 autohandlers 13-31 commonhandler 13-34 keyword activation 8-11 preparing a Rule declaration 6-12 PROC in defining procedures 7-1 PROC RETURN statement 11-19 procedure defining within a rule 7-1 definition 7-1 event declaration 6-6 event handling 7-4 in a MAP statement 7-3 number of statements allowed 7-1 one event for multiple events 6-7 one event for multiple object types 6-7 one event for multiple objects 6-7 using as a function 7-3 using event procedures 7-5 properties Occurs 3-7 referencing nested 4-17 ROLLBACK TRANSACTION file access statements 8-9 ROUND function 5-3 RTRIM for DBCS character strings 5-23 RTRIM() string function 5-18. 13-53 string type converting Java values in ObjectSpeak 13-13 STRLEN for DBCS character strings 5-23 STRLEN() string function 5-18. 13-15. 13-38 CONVERSE REPORT START 11-14. 13-52 SUBSTR 5-20. 13-52 SUBHEADER in CONVERSE REPORT statements 11-14 subrules invoking 11-3 subscript control during compile 6-12 subscript control in calculator arithmetic B-4 in compatible arithmetic B-11 SUBSTR string function 5-20. 13-52 VERIFY 5-19. 13-15. 13-43. 13-43. 13-53 SUBSTR() for DBCS character strings 5-24 subsystems supported 7-5 subtraction operator 4-6 subviews multiply occurring 3-7 symbol constant data item 3-12 symbols in rules 3-12 storing literals in sets 3-12 syntax simple conditions 4-10 syntax flow diagram conventions 1-3 system ID in an alias declaration 3-15 system identifiers 6-11 T TERMINAL clause 11-7 TEXT or IMAGE field mapping to or from 9-8 TIME conversion function 5-11 fields in MAP statements 9-5 format string tokens 5-14 TIME default format string 5-11 TIMESTAMP data type 2-6 function 5-8 TO clause in MAP statements 9-1 transactions client and servlet 13-21 closing semantics and rollback 13-21 committing changes to databases 8-9 EJB 13-21 rollback changes procedures 8-9 transferring objects 2-7 TRUNC (truncate) function 5-4 Index ix . 13-15. 13-52 STRLEN() 5-18. 13-43. 13-42. 13-15 concatenation (++) 4-3 LOWER() 5-18 RTRIM() 5-18. 13-38 CONVERSE REPORT PRINTER 11-14. 13-43. 13-15. 13-53 UPPER() 5-18. 13-38 event handler 13-35 file access 8-4 MAP and SET 9-1 NOWAIT 11-13 ObjectSpeak 8-3 PERFORM 11-17 Post Event 8-10 PROC RETURN 11-19 RETURN 11-16 ROLLBACK TRANSACTION 8-9 START TRANSACTION 8-9 USE 11-2 USE RULE 11-3 using transaction for rollbacks 13-21 storage codes for PIC data type 2-3 string functions CHAR 5-20. 13-15. 13-52 STRPOS 5-19. 13-43. 13-43. 13-43. 13-52 STRPOS string function 5-19.SQL nesting exception 8-5 nesting statements 8-5 qualification 8-5 sample rule 8-8 SQL ASIS Java 8-9 non-Java 8-4 SQL statements 8-4 multiply occurring views in 8-5 START TRANSACTION file access statement 8-9 STARTINTERVAL clause 11-7 STARTTIME clause 11-7 statements assignment CLEAR 9-11 OVERLAY statement 9-12 comment 8-2 COMMIT TRANSACTION 8-9 compiler pragmatic 8-10 CONVERSE REPORT 11-13. 13-43. 13-15. 13-15. truncation rules B-5 in MAP statements 9-3 multiply occurring in SQL statements 8-5 passing to a procedure 7-3 qualifying in SQL code 8-5 returning from a procedure 7-3 SQL Communication Area 8-5 subviews 3-7 U unary minus 4-4 UPPER and LOWER for DBCS character strings 5-23 UPPER() string function 5-18. 13-43. 9-6 VARCHAR field mapping to 9-7 variable converting date and time 2-6 locally declared in DCL 2-9 setting _LEN for C 13-3 setting _LEN for COBOL 13-41 setting _LEN for Java 13-8 setting _LEN for OpenCOBOL 13-49 SMALLINT 2-15 variable-length data types 2-13 variables and literals for double-byte character set functions 5-22 VERIFY string function 5-19. 13-8. 13-43. 13-15. 13-53 VIEW CONTAINS clause 6-4 view includes view relationship 3-7 views comparing views 4-15 defining a local procedure 13-17 defining with LIKE clause 6-3 mapping one to another 9-10 multiply occurring x . 13-52 USE RULE DETACH OBJECT statement 11-5 DETACH statement 11-5 execution environments 11-4 INIT example 11-8 INIT statements 11-7 NEST statement 11-5 rules using rule support 11-4 variations 11-3 USE statement 11-2 Using Occurs property 3-7 Y YEAR conversion function 5-9 YEAR function 5-7 V VARCHAR character data type 2-13 data type length variable 2-15. 13-49 fields in MAP statements 9-5. 13-15. 13-3. 13-41.